Clip Programming

 Top Next

You can significantly extend the functionality of NoteTab by using more sophisticated features of the Clip language. Starting with NoteTab v4.5, you can create quite sophisticated scripts to handle anything from underlining a title to creating complex Web pages. See the following topics to learn about the Clip programming language:

Introduction

Labels

Variables

Events

Custom Functions

Testing Conditions

Message Boxes / Prompts

Text Processing

HTML Processing

Select, Copy, and Insert Text

Clipboard Copy / Paste

Find / Replace Text

Document Processing

Document Management

Outline Documents

Printing Text

Disk Files

Disk Directories

Executing Programs

Using Perl, Gawk, and Other Scripts

Using Other Clips

Clipbars

Menu and Toolbar Commands

Keyboard Macros

Windows Registry and Shortcuts

Miscellaneous Commands / Functions

Mathematics

Dates

Clip Wizard and Fields

Masked Input Fields


Introduction

 Top Previous Next

The Clipbook tool is programmable and supports features such as variables, functions, commands, conditional statements, etc. It also integrates support for Perl and Gawk interpreters; scripts can be stored in Clips and applied directly to highlighted text or a whole document. A good way to learn how the Clip language is used is to look at some of the sample Clipbook libraries provided with NoteTab.

The Clip language has been designed so that it can be mixed with plain text and even other script languages. Because of this, it looks and behaves differently from other programming languages. Clip instructions use tags to clearly delimit them from other text. The language is very easy to learn once you become familiarized with the various syntax elements and their format. Names of the various syntax elements are not case sensitive.

The Clip language understands and uses string (a sequence of characters), integer (negative and positive whole numbers), and Boolean (True/False) data types. However, values are always stored in text format no matter what data type they represent. Conversion between the data types is handled automatically internally. This approach makes the language particularly easy to use even for those with no prior experience in programming.

The "SampleCode.clb" library that is included with NoteTab provides examples for many of the commands and functions explained here. The best way to learn how to use the new Clip language is to look at some of the sample Clips in detail. You can also learn about Clip programming by joining one of the NoteTab mailing lists or by subscribing to the "NoteTab Tips and Tricks" weekly newsletter (information about all this is available at the NoteTab Web site).

Useful tip when testing Clip code:

You can use the "Ctrl+Alt" key combination to stop the execution of a Clip (especially useful when stuck in a loop).

See below for a brief explanation of the various syntax elements.

Clip Language Elements:

Commands:

A command is an instruction that performs a specific task. All commands must start at the beginning of a line with the two-character code "^!" followed either by the name of the Clip command or a program command line. Note that since version 4.8, you can now also have commands after conditional statements. Each command must occupy a single line in the Clip. Many commands accept or require one or more parameters – data that you pass to the instruction that can determine how the command operates. Parameters must be separated with a blank character; if a parameter contains a blank character it must be placed between double-quotes. Example of a command:

^!Close "File Name" SAVE

Functions:

Unlike commands, functions return a result. A function can be placed anywhere in a Clip text but it must not be split by a line break. Functions can also be embedded within each other. Each function is bound by a dollar character "$" and preceded with the circumflex accent "^". Many functions require one or more parameters which must be placed between parenthesis immediately after the function name. If there are several parameters, they must be separated from each other with a semicolon ";". Note that if a parameter contains a semicolon character it must be placed between double-quotes . Example of a function: ^$StrIndex(String;Index)$

Variables:

A variable is a named memory element used for storing values of any data type. It can contain anything from nothing to multiple megabytes of text. A variable can be placed anywhere in a Clip text but it must not be split by a line break. Each variable is bound by a percentage character "%" and preceded with the circumflex accent "^" when referring to the value it contains. A variable is defined as soon as it is used and it is always empty at first – unless you immediately assign a value to it. A variable name can have any character except those that delimit words (space, tab, punctuation, etc.). Example of a variable: ^%MyVariable%

Labels:

Labels are used to mark a place within a Clip to which an instruction can jump. They are useful for controlling the sequence of execution and for creating repeating instructions (loops). A label is defined by starting a line with a colon ":" followed by a name. The name can have any character except those that delimit words (space, tab, punctuation, etc.). You can jump to a label with the ^!Goto command or after a conditional operation. Labels are skipped over when not used within a set of instructions. The scope of a label is limited to the Clip in which it is defined. A Clip should not contain duplicate label definitions (only the first occurrence would be used). Example of a label:

:MyLabel

Events:

Events are triggered when something particular happens in the program or Windows. The Clip language recognizes four distinct events: the opening and closing of a Clipbook library, sending text to the Clipboard, and timer intervals. You can execute Clip code when these events are triggered. Timer events are controlled with the "^!TimerPlay" command; the three other events are defined by creating Clips with the corresponding event name (OnOpen, OnClose, OnClipboardChange).

Comments:

Inserting comments in a Clip is very easy: just place a semicolon (;) at the start of each line containing a comment. If you come across a situation when a line in a Clip should start with a semicolon and it is not a comment, just add an extra semicolon in front of it. Note that comments are only valid within a Clip!

Errors:

When the Clip interpreter encounters a syntax error, it displays an error message and the line in which the fault was encountered. The line number indication, however, does not take into account eventual comments that may have been inserted between the instructions. The reason behind this is that comments are stripped from the code before it is executed.

Parsing and evaluation sequence

A. Whole Clip

1. Comments removed

2. Date fields evaluated ^[...^] (old format)

3. Text selection inserted if ^& found

4. ^!CONTINUE command executed if on first line

5. Clip wizard based on ^?[...] fields displayed

6. Mathematical fields evaluated ^$[...] (old format)

B. Line by line

1. Variables resolved (from right to left)

2. Document name using ^*, ^**, ^#, ^## codes resolved

3. Functions resolved (from right to left)

4. Clip wizard based on ^?{...} fields in line displayed

5. Clip Command executed

Clip Language Topics

Labels

Variables

Events

Custom Functions

Testing Conditions

Message Boxes / Prompts

Text Processing

HTML Processing

Select, Copy, and Insert Text

Clipboard Copy / Paste

Find / Replace Text

Document Processing

Document Management

Disk Files

Disk Directories

Executing Programs

Using Perl, Gawk, and Other Scripts

Using Other Clips

Clipbars

Toolbar Commands

Keyboard Macros

Windows Registry and Shortcuts

Miscellaneous Commands / Functions

Mathematics

Dates

Clip Wizard and Fields

Masked Input Fields


Labels

A label is defined by placing a colon at the beginning of a line followed by the label name. The label name must be at least one character up to any length; it can have any character except word delimiters (space, tab, punctuation, etc.). Character case is ignored. The scope of a label is limited to the Clip in which it has been defined; you cannot jump to a label in another Clip. Example of a label:

:Label

The Clip syntax supports predefined label names which have a special meaning. If you define labels with the same name, you will not be able to use the predefined label for the purpose it was defined for. The following labels are predefined:

NEXT

tells the interpreter to execute the next instruction.

SKIP

will skip the next instruction (text and blank lines are counted, but not commented lines).

SKIP_xx (added in v4.52)

will skip xx lines of Clip code (including blank lines, but not commented lines). xx represents a number (positive or negative). For example, Skip_3 will skip the next three lines in the Clip. "Skip" and "Skip_1" have the same effect.

END

ends the execution of the current clip but continues normally in parent Clip (the Clip from which it was executed, if any).

EXIT

ends the execution of the current clip, including any parent Clip.

Labels are useful to skip instructions or repeat them when a certain condition is met. You can use the "^!Goto" command or one of the conditional testing commands to jump to a specific label.

Useful tip when testing Clip code:

You can use the "Ctrl+Alt" key combination to stop the execution of a Clip (especially helpful when stuck in a loop).

Commands:

^!Goto Label

Continues Clip execution from the specified label defined in the Clip.

^!IfLabelExist LabelName GoToLabelTrue [ELSE GoToLabelFalse] (added in v4.52)

Jumps to the specified label if the indicated label name exists in the active Clip.


Variables

Variables hold data on which a program operates. In the Clip text, the variable's name represents the value of data stored somewhere in the computer memory when the Clip is executed. The data can be anything from nothing to multiple megabytes of text, and can represent a string (a sequence of characters), an integer (negative and positive whole numbers), or a boolean (True/False) data type.

A variable name can be made up of any character except those that delimit words (space, tab, punctuation, carriage return, etc.). The name must also be bound by a percentage character "%". The left side "%" must be preceded with a circumflex accent "^" when you are referring to the value it contains. Example of a variable: ^%MyVariable%. In NoteTab, a variable is defined as soon as its name is encountered in a Clip during execution. A variable can be placed anywhere in a Clip text and can even be used to define a command or function name. If you haven't initially assigned a value to it, the variable is always empty at first.

Variables keep their value as long as the Clipbook is kept open. NoteTab recognizes two types of variables: local variables that exist only within the context of the library that created them (they are cleared if you change libraries or close the Clipbook), and permanent variables that keep their value even when you change libraries (but not if you close the Clipbook). Add the prefix "p_" to define a permanent variable (e.g. ^%p_KeepValue%). If you want to preserve a variable's value even after closing NoteTab, you can store it in an INI file by using the "^!SaveValue" command and then restore it later by using the "^$GetValue()$" function.

Use the "^!Set" command to assign data to a variable. For example:

^!Set %VariableName%=Data

If %VariableName% was never used before, it will be created by the command and then receive the value assigned to it after the equal sign. If %VariableName% already exists, the above command will replace the value it contains with the new data. Note that you must not precede the variable name with a circumflex accent "^" when you assign or change its value.

You can also assign values to multiple variables using a single "^!Set" command. An assignment must be separated from the next one with a semicolon and a blank character "; ". For example:

^!Set %V1%=Value1; %V2%=Value2; %V3%=Value3

Note that the last assignment does not end with a semicolon.

Note that you must use the curly braces format ^?{ } rather than the square brackets ^?[ ] if you want to assign the result from a Clip wizard memo field. Example:

^!Set %NewVariable%=^?{(T=M)Message}

To use the data contained in a variable, just precede the variable name (bound by "%" characters) with a circumflex accent: ^%VariableName% anywhere in the Clip where you want to use it. Note that you cannot define a label with a variable. So, for example, the following will not work (the line is just ignored):

:^%VariableName%

Note that you can set the value of a variable with the data contained in another variable by using the following instruction:

^!Set %NewVariable%=^%OtherVariable%

The Clipbook also provides predefined variables. Unlike other variables, they already contain a value when you first use them. You may, however, reassign other values to them if you wish. These are the predefined variables and the data they contain:

^%AR_KEY% = Auto-replace activation key (added in v4.6)

^%AR_WORD% = Auto-replace text (added in v4.9)

^%CARET% = caret (^) (added in v4.6)

^%COLON% = colon (:)

^%DOLLAR% = Dollar character ($) (added in v5.0)

^%EMPTY% = empty string

^%NL% = new line (CR/LF pair)

^%PAGE% = Page break

^%RESULT%= Used to assign result to custom functions (added in v4.8)

^%SC% = semicolon (;)

^%SPACE% = Blank space character

^%TAB% = Tab character

^%VBAR% = vertical bar (|) (added in v4.6)

In addition, since version 5.7 a variety of system variables can be accessed using ^$ExpandEnv$ with file and folder tokens. For details, view Folder and File Tokens in the Main Help File.

Commands:

^!Append %Variable%=Value

Appends value to the content of %Variable%. This command also has the advantage of allowing assignments of function names and ^?{} prompts without causing these to be evaluated. This command is particularly useful for creating sophisticated Clip Wizards.

^!ClearValue [Section:]Key

Deletes the specified key in NoteTab's INI file, or in the INI file defined by the ^!SetIniFile command. If a section name is not defined, the key entry is searched under the [ClipValues] section. Section names are only supported since version 4.51.

^!ClearValues [Section]

Deletes all the keys under the specified section in NoteTab's INI file, or in the INI file defined by the ^!SetIniFile command. If a section name is not defined, the [ClipValues] section will be cleared. Section names are only supported since version 4.51.

^!ClearVariable %VariableName%

Empties the specified variable.

^!ClearVariables

Clears all variables (including those defined as permanent).

^!Dec VariableName [nn]

Subtracts 1 from specified variable (decrement). If you use the second optional parameter "nn", you can specify a different decrement value. For example, if %var% contains the value 30 and you apply the command "^!Dec %var% 7" to it, the new value will be 23.

^!Inc VariableName [nn]

Adds 1 to specified variable (increment). If you use the second optional parameter "nn", you can specify a different increment value. For example, if %var% contains the value 23 and you apply the command "^!Inc %var% 7" to it, the new value will be 30.

^!ProgIniLoad [IniName] (added in v4.6)

Loads options from the NoteTab ini file or registry. Optionally, you can specify an alternative INI file (it must exist or else the command sets the error condition). Note that the [AutoLoad] section is ignored by this command.

^!ProgIniSave [IniName] (added in v4.6)

Saves the current program settings into the NoteTab ini file or registry. Optionally, you can specify an alternative INI file (it is automatically created if it does not exist).

^!SaveValue [Section:]Key=Value

Saves the key and its value in NoteTab's INI file, or in the INI file defined by the ^!SetIniFile command. If a section name is not defined, the key entry is written under the [ClipValues] section. Section names are only supported since version 4.51. The maximum amount of text that can be saved this way is 1024 characters. Example:

^!SaveValue MySection:UserName=Raymond

^!Set %VariableName%=Value

or

^!Set %VariableName%=^%OtherVariable%

or

^!Set %V1%=Value1; %V2%=Value2; %V3%=Value3

Assigns Value to VariableName. The variable name may not contain blanks or other word-delimiting characters. The value can be a string, an integer, or a boolean data type. It can also refer to the value of another variable.

^!SetArray %VariableName%=ArrayData (added in v4.6)

Similar to the ^!Set command but creates an array from the data assigned to it. By default, the data delimiter is a plain semi-colon (;), or a semi-colon and double-quotes separating each item. You can change the default delimiter with the command ^!SetListDelimiter (see below). During the assignment, the individual items from the ArrayData are each stored in a new variable with the same name as the base variable plus an index number reflecting their corresponding position. The variable at index 0 has a special purpose as it stores the actual number of items contained in the array. You can change the values of the individual indexed items by using the ^!Set, ^!Inc, ^!Dec commands, and the changes are reflected in the base variable. If you assign an empty value to an array variable, or use the ^!Set command to assign a new value to it, the array is automatically removed from memory.

Examples:

^!SetArray %Array%="Value 1";"Value 2";"Value 3"

The above instruction will create four new variables:

^%Array0% = 3

^%Array1% = Value 1

^%Array2% = Value 2

^%Array3% = Value 3

If we assign a new value to the second item, as follows:

^!Set %Array2%=New Value

then accessing the base variable ^%Array% will return:

"Value 1";"New Value";"Value 3"

The following assignment will destroy the array, and only the base variable will be preserved with the newly assigned value:

^!Set %Array%=Another Value

^!SetCode %VariableName%=Value (added in v4.84)

Similar to the ^!Set command, but assigns the value without interpreting ^?{} prompts and Clip tokens like ^P, ^T, ^&, ^#, etc. However, variables and functions used in the assigned value are evaluated normally. You cannot set multiple variables with this command.

^!SetIniFile Name (added in v4.51)

Defines where Clip variables are saved when using the SaveValue, ClearValue, and ClearValues commands and the GetValue function. By default, variables are saved in NoteTab's INI file (or registry if so configured). Use this command to define a different INI file. If you do not specify a path in the name, the specified INI file will be created in the Libraries directory. If you plan to distribute your library file, consider giving your INI file the same name as your library file (without the extension); you can use the ^$GetLibraryName$ for this purpose. The scope of this command is limited to the library in which it is invoked. It is reset when you change libraries or close the Clipbook. Invoke the command with no name to reset NoteTab's INI file as the default.

^!SetListDelimiter Value (added in v4.6)

Defines a delimiter to be used by the ^!SetArray command or Clip Wizard fields using the new Checkbox list (see below). Tokens are accepted, but the delimiter must not be more than 10 characters. The scope of this command is limited to the current Clip. Assigning an empty value results in using the default semi-colon (;) delimiter. Example: ^!SetListDelimiter ^p^p

Functions:

^$GetIniFile$

Returns the name of the INI file defined by the SetIniFile command. Returns a blank string if NoteTab's INI file is used.

^$GetValue("[Section:]Key")$

Reads the specified key in NoteTab's INI file, or in the INI file defined by the ^!SetIniFile command. If a section name is not defined, the key entry is searched under the [ClipValues] section. Section names are only supported since version 4.51. Returns the value assigned to the key. Returns an empty string if the key does not exist. Example based on ^!SaveValue example: ^$GetValue(MySection:UserName)$ -> Raymond


Events

An event is an action that takes place on a system level – showing or resizing a window for example, or the movement of a mouse. The Clip language recognizes four distinct events:

1. the opening of a Clipbook library;

2. the closing of a Clipbook library;

3. the Windows Clipboard receiving text;

4. and timer events that are triggered at defined time intervals.

You can execute Clip instructions when these events are triggered. Timer events are controlled with the "^!TimerPlay" command; the three other events are defined by creating Clips with the corresponding event name (OnOpen, OnClose, OnClipboardChange). When the event is triggered, the corresponding Clip is executed.

H="OnOpen"

Automatically executes the OnOpen Clip when library is opened. Holding the Shift key down cancels the execution of the Clip.

H="OnClose"

Automatically executes the OnClose Clip when library is closed (either by changing to another library or by closing the Clipbook). Holding the Shift key down cancels the execution of the Clip.

H="OnClipboardChange"

Automatically executes content of the OnClipboardChange Clip whenever text is copied to the Windows Clipboard. Note that you must close libraries containing this type of Clip if you no longer want to capture text changes to the Clipboard.

Timer Commands:

^!TimerPlay ClipName

Assigns the Clip instructions to the timer memory. The instructions remain available even when you change libraries but are cleared when you close the Clipbook.

^!TimerStart nnnn

Defines an event timer. nnnn represents the interval in milliseconds. For example, "^!TimerStart 5000" will execute the assigned Clip (set with "^!TimerPlay") every 5 seconds. Note that the Clip is not executed if the Clipbook is already in the process of executing another Clip.

^!TimerStop

Stops the timer and clears the assigned Clip instructions.


Custom Functions

Since NoteTab 4.8, you can create your own Clip functions, using an approach that is similar to the ^!Clip command. Custom Clip functions must not have the same name as a predefined function. The function name corresponds to the name of the Clip that contains the code. You can create functions that take one parameter or none. You can access the parameter data in your function script by using the ^& code. Your function script must assign the result to the new ^!Result command, or by using the new predefined variable %Result%. Example:

H="Double"

^!IfTrue ^$IsNumber("^&")$ Multiply

^!Result ^&^&

^!Goto End

:Multiply

^!Result ^$Calc(^& * 2)$

H="TestDouble"

^!Prompt ^$Double(^?[Enter a number or some text])$

Note that Clips using custom functions cannot be run from the Clipbar.


Testing Conditions

The Clip language includes many commands and functions to test conditions within the NoteTab environment. You can use these tests to control which instructions are executed based on one condition or another. See below the commands and functions that are available for controlling the operational flow:

Note that NoteTab Light 4.6 and earlier (with trial mode not enabled) only supports the predefined label "Exit".

New since NoteTab 4.8: conditional commands now accept a command statement instead of a label. The second command statement may not be another conditional command, and it may not be followed by an ELSE-type label. Examples:

^!If ^%Variable% < 0 ^!Set %Variable%=0

^!IfFileExist "^%Variable%" GoToLabelTrue ELSE ^!Prompt File does not exist

Commands:

^!Continue [Question]

Displays a message box with an OK and Cancel button. If the user clicks on the OK button, the Clip execution continues normally. If the Cancel button is pressed then Clip execution is halted at that point. NoteTab checks if this instruction is the first to execute in a Clip; if this is the case it will be displayed before the main Clip Wizard (if any).

^!If Integer1 <>= Integer2 GoToLabelTrue [ELSE GoToLabelFalse]

or

^!If "String1" <>= "String2" GoToLabelTrue [ELSE GoToLabelFalse]

If the comparison result is true, then jumps to the specified GoToLabelTrue label. If the result is false and the optional ELSE keyword follows the first label name, execution jumps to the specified GoToLabelFalse label; or to the next instruction if the "ELSE" label is not used. If the two values represent numbers then they are compared as numbers, otherwise they are compared as strings. String comparison is case sensitive.

You can use the following comparison operators:

< returns True if left value is smaller than right value

> returns True if left value is greater than right value

<> returns True if left value is different from right value

<= returns True if left value is smaller or equal to right value

>= returns True if left value is greater or equal to right value

= returns True if left value is equal to right value

Examples:

The following will cause the execution to jump to the label defined as IsTrue:

^!If "Apple" <> "Orange" IsTrue ELSE IsFalse

The following will cause the execution to jump to the label defined as LabelFalse:

^!If 16 < 7 LabelTrue ELSE LabelFalse

^!IfAppOpen AppTitle GoToLabelTrue [ELSE GoToLabelFalse] (added in v4.52)

Jumps to the specified label if a window with the indicated title caption is found. For example, if the Windows calculator utility is open, the following command will continue execution after the CalcOpen label:

^!IfAppOpen Calculator CalcOpen

Most applications usually show other information in the title bar. For these cases, you can use an asterisk "*" either at the beginning or the end of the AppTitle text to specify that the text should match the end or the beginning of the title respectively. For example, MS Wordpad displays the document name in front of the program name, so the following instruction will work if Wordpad is open:

^!IfAppOpen *WordPad WordPadOpen

^!IfCancel GoToLabel

Jumps to specified label if a Clip Wizard built from "^?{}" fields has been canceled. If the Clip doesn't contain such a statement or if it does not appear after the call to the Clip Wizard and before the next one, then its execution is aborted.

^!IfClipExist "ClipName" GoToLabelTrue [ELSE GoToLabelFalse]

Jumps to label if the specified Clip exists.

^!IfDiff "Value1" "Value2" GoToLabelTrue [ELSE GoToLabelFalse]

Compares two string values. The comparison is not case sensitive.

Example:

The following will cause the execution to skip the next instruction (Skip is a predefined label):

^!IfDiff "abc" "xyz" Skip

^!IfEmpty "Value" GoToLabelTrue [ELSE GoToLabelFalse] (added in v5.4)

If Value represents an empty variable or string, then jumps to specified label name. It is recommended to enclose Value between double quotes.

^!IfError GoToLabelTrue [ELSE GoToLabelFalse]

If the previous command fails for one reason or another, it sets an error state that can be detected with "^!IfError". If the previous command failed, then execution will jump to specified label. Note that support for ELSE was added in NoteTab v4.51.

^!IfFalse Value GoToLabelTrue [ELSE GoToLabelFalse]

If Value is an empty string or equal to 0, FALSE, NO, N, or OFF (case insensitive), then jumps to specified label name. Do not use comparison operators with this command; in that case, you should use the ^!If command to do a comparison between two values.

^!IfFileAttr "FileName" Attr GoToLabelTrue [ELSE GoToLabelFalse] (added in v4.8)

Compares FileName attributes with Attr. If Attr is equal or a subset of FileName's attributes, then GoToLabelTrue is activated. Attr can represent multiple values: A = Archive, D = Directory, H = Hidden, R = Read-only, S = System, V = VolumeID, * = All attributes. Example:

^!IfFileAttr "c:\Scandisk.log" AH LabelTrue ELSE LabelFalse

If Scandisk.log has at least the Archive and Hidden attributes set, then the instruction jumps to LabelTrue.

^!IfFileUnicode "FileName" GoToLabelTrue [ELSE GoToLabelFalse]

Jumps to specified label if FileName is a Unicode text file or UTF-8 Web page.

^!IfFileExist "FileName" GoToLabelTrue [ELSE GoToLabelFalse]

Jumps to specified label if FileName exists.

^!IfInDateRange yyyy/mm/dd-hh:nn yyyy/mm/dd-hh:nn..yyyy/mm/dd-hh:nn GoToLabelTrue [ELSE GoToLabelFalse]

Similar to IfInRange command but takes dates as arguments instead of integers. The date value can have the following formats (yyyy=year, mm=month, dd=day, hh=24 hour, nn=minutes):

yyyy/mm/dd-hh:nn

1998/07/13-16:30

yyyy/mm/dd

1998/07/13

hh:nn

16:30

^!IfInRange Value Range1..Range2 GoToLabelTrue [ELSE GoToLabelFalse]

Applies only to numerical values. If Value is in the range defined from Range1 to Range2, then jumps to GoToLabelTrue. For example: "^!IfInRange 23 20..30 DoThis" will jump to the label ":DoThis"

^!IfLabelExist LabelName GoToLabelTrue [ELSE GoToLabelFalse] (added in v4.52)

Jumps to the specified label if the indicated label name exists in the active Clip.

^!IfMatch "RegExp" "Value2" GoToLabelTrue [ELSE GoToLabelFalse] (added in v4.8)

Similar to ^!IfSame, but accepts a regular expression for the first value.

^!IfRegexOk Pattern GoToLabelTrue [ELSE GoToLabelFalse] (added in v5.0)

Jumps to the specified label if the regex pattern is valid. If the pattern has mistakes and the optional ELSE keyword follows the first label name, execution jumps to the specified GoToLabelFalse label; or to the next instruction if the "ELSE" label is not used.

^!IfPathExist "PathName" GoToLabelTrue [ELSE GoToLabelFalse]

Jumps to specified label if PathName exists.

^!IfSame "Value1" "Value2" GoToLabelTrue [ELSE GoToLabelFalse]

Compares two string values. The comparison is not case sensitive.

Example:

The following will cause the execution to jump to the label defined as GoToLabelTrue:

^!IfSame "abc" "ABC" GoToLabelTrue

^!IfTrue Value GoToLabelTrue [ELSE GoToLabelFalse]

If Value is equal to 1, TRUE, YES, Y, or ON (case insensitive), then jumps to specified label name. Do not use comparison operators with this command; in that case, you should use the ^!If command to do a comparison between two values.

^!Skip Question

Skips next instruction if the user answers Yes.

Functions:

^$IsAlpha("Str")$ (added in v4.8)

Returns 1 if Str contains only characters from the alphabet, and 0 if it does not.

^$IsAlphaNumeric("Str")$ (added in v4.8)

Returns 1 if Str contains only numbers and characters from the alphabet, and 0 if it does not.

^$IsAltKeyDown$ (added in v4.8)

Returns 1 if the Alt key is pressed while the function is executed and 0 if it is not.

^$IsAutoIndent$

Returns 1 if AutoIndent is enabled in current document and 0 if it is turned off.

^$IsBlank("Str")$ (added in v4.8)

Returns 1 if Str contains only blank characters (tabs, spacebar, line breaks, etc.), and 0 if it does not.

^$IsCapitalized("Str")$ (added in v4.8)

Returns 1 if Str does not start with a lowercase character and is not followed by any uppercase characters, and 0 if this condition is not met.

^$IsClipDoc$

Returns 1 if current document is the [Clip] editor, or 0 if it is not.

^$IsCtrlKeyDown$ (added in v4.8)

Returns 1 if the Control key is pressed while the function is executed and 0 if it is not.

^$IsEmpty(Value)$

Returns 1 if the value/variable is empty and 0 if it contains data.

^$IsFileType("FileName";"extensions")$

Returns 1 if the extension of FileName is listed in "extensions", or 0 if turned off. Multiple extensions must be delimited with a comma. The following example returns 1:

^$IsFileType("c:\temp\MyFile.txt";"html,txt,otl,ini")

^$IsFullVersion$

Returns 1 if NoteTab is the commercial version and 0 if it is the Freeware or trial version.

^$IsHex(Value)$ (added in v4.52)

Returns 1 if specified text is a hexadecimal number and 0 if it is not.

^$IsHtmlDoc$

Returns 1 if current document is HTML type document, or 0 if it is not.

^$IsLightVersion$

Returns 1 if the NoteTab program currently running is the Freeware version (trial mode not enabled), or 0 if it is not.

^$IsLowercase("Str")$ (added in v4.8)

Returns 1 if Str does not contain any uppercase characters, and 0 if it does.

^$IsMixedCase("Str")$ (added in v4.8)

Returns 1 if Str contains both lowercase and uppercase characters, and 0 if it does not. Note that text that is capitalized is not considered mixed case.

^$IsModified$

Returns 1 if current document needs saving, or 0 if it is not modified.

^$IsNumber(Value)$

Returns 1 if specified text is a number and 0 if it is not.

^$IsOpen("DocumentName")$

Returns 1 if specified document is open in NoteTab and 0 if it is not.

^$IsOutlineDoc$

Returns 1 if current document is Outline type document, or 0 if it is not.

^$IsPasteBoard$

Returns 1 if current document is the Paste Board, or 0 if it is not.

^$IsPasteIndent$ (added in v4.8)

Returns 1 if Clips insert text with automatic indenting and 0 if not.

^$IsReadOnly$

Returns 1 if current document is Read-Only, or 0 if it is not.

^$IsSecondWindow$

Returns 1 if current document is in the second window, or 0 if it is not.

^$IsShiftKeyDown$ (added in v4.8)

Returns 1 if the Shift key is pressed while the function is executed and 0 if it is not.

^$IsShowHeadings$ (added in v4.52)

Returns 1 if headings are displayed in the outline document window and 0 if they are not.

^$IsTopStyleEnabled$ (added in v4.8)

Returns 1 if the TopStyle editor is available through NoteTab, and 0 if it is not.

^$IsTrimBlanks$ (added in v4.6)

Returns 1 if the option "Trim White Spaces" is enabled in current document and 0 if it is turned off.

^$IsUppercase("Str")$ (added in v4.8)

Returns 1 if Str does not contain any lowercase characters, and 0 if it does.

^$IsUrl("AnyText")$

Tests if parameter is a URL or not. It returns 1 to indicate True and 0 to indicate False.

^$IsWildcard("FileName")$ (added in v4.82)

Returns 1 if FileName contains one or more wildcard characters (* and ?), and 0 if it does not.

^$IsWordWrap$

Returns 1 if word wrap is active in current document, or 0 if turned off.


Message Boxes / Prompts

Use message boxes to prompt users for an answer or to inform them of what is being done. See also Wizard Dialog and Fields for related information.

^!Continue [Question]

Displays a message box with an OK and a Cancel button. If the user clicks on the OK button, the Clip execution continues normally. If the Cancel button is pressed then Clip execution is halted at that point. NoteTab checks if this instruction is the first to execute in a Clip; if this is the case it will be displayed before the main Clip Wizard (if any).

^!Info [Alignment:L|C|R]Multiline message

Displays a Web-enabled scrollable message window. The text can be up to about 40 KB in size. Users can double-click on links or e-mail addresses in the text to open them in their browser or e-mail program respectively. Authors of Clipbook libraries can use this feature to advertise their work. Use the token "^P" to indicate line breaks in your text. By default, lines displayed in the window are centered. You can use the alignment parameter (character between square brackets) to change the setting:

[L] = Left aligned

[C] = Centered

[R] = Right aligned

Users can change the default font used for the text by right clicking in the text area to open the shortcut menu, then choosing the Font command to open the font dialog box.

The following example will display a dialog box with two left-aligned lines:

^!Info [L]You can find more Clipbook libraries from^Pwww.notetab.com/libraries.htm

Other examples are provided in the libraries packaged with NoteTab.

^!Prompt [Message]

Displays a message box with the specified text (optional). The user must click on the OK button to continue Clip execution.

^!SetDebug [On|Off] (added in v4.8)

When enabled, a dialog box pops up just before each statement and paste operation is executed. The dialog box shows the parsed instruction or the text about to be pasted in the document. There are three buttons; "Yes" is for continuing execution until the next instruction, "No" disables Debug mode, and "Cancel" ends Clip execution.

^!SetDebug "FileName" (added in v5.3)

When you specify a filename instead of "On" or "Off", NoteTab will save the parsed Clip instructions to the file instead of displaying them in a dialog box. If no pathname is specified, the log file is saved under the "<APPDATA>\NoteTab Pro\Libraries" folder. Example:

^!SetDebug Log.txt

^!SetHintInfo AnyText

Turns the status bar Clip messages on or off. When you specify text, it will be displayed in the status bar instead of the usual Clip messages. To re-enable the display of normal Clip messages, just invoke the command without any text. This command only has an effect during the time the Clip is running.

^!Skip [Question]

Skips next instruction if the user answers Yes.

^!StatusClose

Closes the modeless status window opened with the ^!StatusShow command.

^!StatusShow Message

Shows a modeless status window. Useful for providing feedback to the user during long processes. If the Window is already open, the current message is replaced by the new one. The window is automatically closed when the Clip ends.


Text Processing

Use the following functions to analyze or modify text data.

Commands:

^!DirectPrint "Title" Data (added in v4.8)

Prints text directly to the printer, bypassing NoteTab's print procedure. Uses default printer settings. Title is the text shown in the Print manager and Data is the text to send directly to the printer. Data can contain printer control codes.

Functions:

^$CharToDec(Character)$ (added in v4.8)

Returns the decimal value of Character. Example:

^$CharToDec(S)$ -> 83

^$DecToChar(Decimal)$ (added in v4.8)

Returns the character corresponding to the decimal value. Example:

^$DecToChar(83)$ -> S

Note that you should avoid converting the following decimal values 1, 4, 5, and 6 to characters as they have a special meaning for the Clip interpreter.

^$HexToInt(Value)$ (added in v4.52)

Returns the specified hexadecimal value as an integer.

^$IntToHex(Value)$ (added in v4.52)

Returns the specified integer value as an hexadecimal number. In version 4.8, also returns the ANSI hex code of single character if Char does not represent a number.

^$IsAlpha("Str")$ (added in v4.8)

Returns 1 if Str contains only characters from the alphabet, and 0 if it does not.

^$IsAlphaNumeric("Str")$ (added in v4.8)

Returns 1 if Str contains only numbers and characters from the alphabet, and 0 if it does not.

^$IsBlank("Str")$ (added in v4.8)

Returns 1 if Str contains only blank characters (tabs, spacebar, line breaks, etc.), and 0 if it does not.

^$IsCapitalized("Str")$ (added in v4.8)

Returns 1 if Str does not start with a lowercase character and is not followed by any uppercase characters, and 0 if this condition is not met.

^$IsHex(Value)$ (added in v4.52)

Returns 1 if specified text is a hexadecimal number and 0 if it is not.

^$IsLowercase("Str")$ (added in v4.8)

Returns 1 if Str does not contain any uppercase characters, and 0 if it does.

^$IsMixedCase("Str")$ (added in v4.8)

Returns 1 if Str contains both lowercase and uppercase characters, and 0 if it does not.

^$IsNumber(Value)$

Returns 1 if specified text is a number and 0 if it is not.

^$IsUppercase("Str")$ (added in v4.8)

Returns 1 if Str does not contain any lowercase characters, and 0 if it does.

^$RemoveTokens("Str")$

Converts tokens to their corresponding control characters (tabs, carriage returns, etc.)

^$StrAlign("Str";TextWidth;Alignment[;Pad=False])$ (added in v4.9)

This function aligns the Str value within a space specified by TextWidth. Alignment values can be Left, Right, or Center. If the Pad parameter is used, a True value adds blank spaces on the right side of Str (if necessary). Examples:

^$StrAlign("Test";10;Right)$ -> " Test"

^$StrAlign("Test";10;Center;True)$ -> " Test "

^$StrAsciiToAnsi("Str")$ (added in v4.8)

Returns Str with all extended ASCII characters converted to ANSI. This feature uses a conversion table based based on ASCII 850 Multilingual (Latin I).

^$StrAnsiToAscii("Str")$ (added in v4.8)

Returns Str with all extended ANSI characters converted to ASCII. This feature uses a conversion table based based on ASCII 850 Multilingual (Latin I).

^$StrAnsiToOem("Str")$ (added in v4.9)

Returns Str based on ANSI-defined character set converted to OEM.

^$StrCapitalize("Str")$ (added in v4.8)

Capitalizes all words in Str and returns the resulting string.

^$StrCopy("Str";Index;Amount)$

Returns a substring of Str starting at position Index and a size determined by Amount. Example:

^$StrCopy("abcdefghi";4;3)$ -> def

^$StrCopyLeft("Str";Amount)$ (added in v4.82)

Similar to ^$StrCopy()$ but copies the substring from the start of the specified string.

^$StrCopyRight("Str";Amount)$ (added in v4.52)

Similar to ^$StrCopy()$ but copies the substring from the end of the specified string.

^$StrCount("SubStr";"Str";CaseSensitive;WholeWord)$

Returns the number of occurrences of SubStr in Str. Use the CaseSensitive parameter to determine if the match should be case sensitive or not, and WholeWord to indicate that SubStr must only match whole words. Example:

^$StrCount("t";"NoteTab";False;False)$ -> 2

^$StrDecrypt("Text";[Key])$ (added in v4.84)

Decrypts text encrypted with the ^$StrEncrypt("Text";[Key])$ function. You must use the same encryption key to decrypt the text. Requires the ntb_enc.dll file. Example:

^$StrDecrypt("^$GetSelection$";"^?[key=My secret password]")$

^$StrDelete("Str";Index;Amount)$

Returns the resulting string with a deleted portion starting at position Index and a size determined by Amount. Example:

^$StrDelete("abcdefghi";4;3)$ -> abcghi

^$StrDeleteLeft("Str";Amount)$ (added in v4.82)

Similar to ^$StrDelete()$ but deletes the text from the start of the specified string.

^$StrDeleteRight("Str";Amount)$ (added in v4.82)

Similar to ^$StrDelete()$ but deletes the text from the end of the specified string.

^$StrEncrypt("Text";[Key])$ (added in v4.84)

Provides stronger text encryption than ROT13. Use the optional "Key" parameter to define an encryption password (maximum 255 characters and case sensitive). Make sure you don't forget the key you used with this function, otherwise you may never be able to retrieve your encrypted text. Requires the ntb_enc.dll file. Note that although the encryption algorithm is very good, there is no guarantee that it can't be cracked. You should not rely on it to protect very sensitive data. Example:

^$StrEncrypt("^$GetSelection$";"^?[key=My secret password]")$

^$StrFill("Str";Amount)$

Returns a string entirely composed of the defined character or text repeated Amount times. Examples:

^$StrFill(+;4)$ -> ++++

^$StrFill("<>";4)$ -> <><><><>

^$StrFixLines("Str")$ (added in v4.51)

Corrects carriage returns in text criteria (Unix and Mac-formatted text is converted to Dos/Windows format).

^$StrFormat("Str";LeftMargin;TextWidth;Justify)$

Returns the "Str" string in specified format. LeftMargin determines the number of blank spaces to insert between the left margin and the text; TextWidth defines the maximum width of the text in each line; Justify is either True or False and determines if the text is left and right justified. Prior to version 4.8, this command was only available in the commercial and trial versions of NoteTab.

^$StrIndent("Str";IndentSize)$ (added in v4.9)

Returns the Str value with each line indented by IndentSize number of blank characters.

^$StrIndex("Str";Index)$

Returns the character at position Index in Str. Returns an empty string if an invalid Index value is specified. Example:

^$StrIndex("abcdefghi";4)$ -> d

^$StrInsert("SubStr";"Str";Index)$

Returns a string composed of SubStr inserted at position Index in Str. Example:

^$StrInsert("xyz";"abcdefghi";3)$ -> abxyzcdefghi

^$StrInvertCase("Str")$ (added in v4.8)

Converts all uppercase characters to lowercase, and lowercase characters to uppercase, and returns the resulting string.

^$StrLower("Str")$

Returns Str with all characters in lower case. Example:

^$StrLower("ABCdefGHI")$ -> abcdefghi

^$StrOemToAnsi("Str")$ (added in v4.9)

Returns Str based on OEM-defined character set converted to ANSI.

^$StrPos("SubStr";"Str";CaseSensitive)$

Returns the index position of SubStr in Str. Use the CaseSensitive parameter to determine if the match should be case sensitive or not. Returns 0 if there is no match. Tab and line-break tokens are automatically converted to their real characters since version 4.6. Example:

^$StrPos("def";"abcdefghi";True)$ -> 4

^$StrPosMid("SubStr";"Str";StartIndex;CaseSensitive)$ (added in v4.52)

Similar to the ^$StrPos()$ function but starts searching from the specified index position.

^$StrPosRight("SubStr";"Str";CaseSensitive)$ (added in v4.52)

Similar to the ^$StrPos()$ function but searches from right to left.

^$StrRandom(Size)$ (added in v4.84)

^$StrRandom(Size[;Characters])$ (added in v4.85)

Returns a string of random characters of the specified length. This function can be useful for generating random passwords. Example

^$StrRandom(6)$ = È$q3åî

Starting with version 4.85, the StrRandom has been updated to let you optionally define which characters are used in the random string that is generated. The "Characters" parameter represents a string of characters that limits what the function can use in its result. You can define ranges by using "..". For example, A..Z represents all the uppercase letters of the Roman alphabet; A..Za..z0..1 represents all digits and letters of the Roman alphabet. Example:

^$StrRandom(10;A..F0..9)$ --> D744E70176

^$StrReplace("SubStr";"ReplaceStr";"Str";CaseSensitive;WholeWord)$

Returns a new string with all occurrences of SubStr replaced with ReplaceStr according to the settings of the CaseSensitive and WholeWord parameters. Tab and line-break tokens are automatically converted to their real characters since version 4.6. Example:

^$StrReplace("o";"?";"NoteTab Pro";True;False)$ -> N?teTab Pr?

^$StrROT13("Str")$ (added in v4.84)

Performs a ROT13 operation on the specified text. Useful for rendering text unreadable to others. Repeat the function on the text to render it readable again.

^$StrSentenceCase("Str")$ (added in v4.8)

Capitalizes all words following a period, exclamation, and question mark and converts all other words to lowercase.

^$StrSize("Str")$

Returns the size of Str. Example:

^$StrSize("abcdefghi")$ -> 9

^$StrSplit("Str";TextWidth;TrimLines)$ (added in v4.6)

Returns the "Str" string with long lines split at specified width. TextWidth defines the maximum width of the text in each line; TrimLines is either True or False and determines if blank spaces at the end of each line are removed or not.

^$StrSort("Str";CaseSensitive;Ascending;RemoveDuplicates)$ (added in v4.52)

Returns the specified text "Str" sorted according to the defined criteria. NoteTab 5 supports two new values for the CaseSensitive parameter: ANSI to enforce a case sensitive dictionary-type sorting order and False_ANSI to ignore character case during sorting. The ANSI option produces a sorting order that matches the result from the Modify/Lines/Sort menu command. Note, however, that sorting is much slower with the ANSI option.

For example, the following instruction will sort the lines contained in the Clipboard, in ascending order, ignoring character case, and removing duplicates:

^$StrSort("^$GetClipboard$";False;True;True)$

^$StrStripHTML("Str";PreserveURLs)$ (added in v4.82)

Returns a copy of Str with all HTML tags removed. PreserveURLs is either True or False, and determines if URLs are preserved or not.

^$StrTrim("Str")$

Removes blank spaces from the start and end of the specified value. Example:

^$StrTrim(" some text ")$ returns "some text"

^$StrUpper("Str")$

Returns Str with all characters in upper case. Example:

^$StrUpper("abcdefghi")$ -> ABCDEFGHI

^$StrUrlDecode("Str")$ (added in v4.86c)

Cconverts URL strings and form Mailto data to plain text. Example:

^$StrUrlDecode("C%3A%5CProgram%20Files%5CReadme%2Etxt")$ --> C:\Program Files\Readme.txt

^$StrUUDecode("Str")$ (added in v4.84)

Decodes UUEncoded text converted with the ^$StrUUEncode("Str")$ function. Example:

^$StrDecrypt("^$StrUUDecode("^$GetText$";)$")$

^$StrUUEncode("Str")$ (added in v4.84)

Converts the specified text to 7-bit UUEncoded format. This encoding format is frequently used to send 8-bit data through transmission media (email, for example) supporting only 7-bit data. This function is very useful if you want to send encrypted text by email. Example:

^$StrUUEncode("^$StrEncrypt("^$GetText$";)$")$

Important note: UUencoded text may contain characters that the Clip parser interprets as tokens, like ^p and ^&. As a result, you should use the ^!SetCode command to assign such data to a variable and ^!InsertCode to paste the result of ^$StrUUEncode("Text")$ into a document. See the example in the Utilities library.

^$UseTokens("Str")$

Converts control characters (tabs, carriage returns, etc.) to their corresponding tokens.


HTML Processing

Use the following commands and functions to process HTML code.

Commands:

^!InsertHtml Any text with tokens (^p/^t) (added in v4.8)

Similar to ^!InsertText command, but converts HTML tags to Uppercase, Lowercase, or XHTML format (depending on settings in Options). This command is sensitive to the "Indent on Paste" setting in the Options dialog box on the Clipbook tab. You can precede it with the command

^!SetPasteIndent Off

to make it ignore the indent setting.

^!InsertWizardHtml Any text with tokens (^p/^t) (added in v4.8)

Similar to ^!InsertHtml command, but removes attributes that have no value. This command is useful when used together with the Clip wizard. It allows the user to leave certain fields blank in the Wizard, and the corresponding tags are then automatically removed before being inserted in the document. Example:

^!InsertWizardHtml <TD ALIGN="" WIDTH="">

will insert the following tag in your document: <TD>

^!RunTidy [i|d] (added in v4.8)

^!RunTidy [Switches]

HTML Tidy is a free utility that cleans HTML code and fixes errors. This new Clip command will send your document text to the HTML Tidy program. The corrected output returned by HTML Tidy is then inserted into the document. The StdError stream is saved in a file called "StdError.err" in NoteTab's application directory, unless another file is specified with the SetStdError Name command. You can use the optional parameter "Switches" to specify Tidy command-line arguments; example:

^!RunTidy -f errs.txt -qiu

If no argument is specified and you have a Tidy.cfg file in the NoteTab folder, then HTML Tidy will be configured according to the settings in that configuration file. If NoteTab does not find the configuration file, it will determine the appropriate switches based on the settings in NoteTab. If you have a Tidy.cfg file, but you want NoteTab to ignore it and use default settings, then use the "d" argument (without the quotes). If you want NoteTab to determine the best settings, but would like to have your tags indented, just use the "i" argument; example:

^!RunTidy i

You can learn more about HTML Tidy and download the latest version by visiting the following Web page:

http://tidy.sourceforge.net/

The easiest setup is to copy the Tidy program to the NoteTab folder (rename the file to Tidy.exe if necessary), but you may place it anywhere else if you prefer.

^!SetHtmlFormat [UPPERCASE|LOWERCASE|XHTML] (added in v4.801)

Sets the default format of HTML tags created by NoteTab.

Functions:

^$GetHtmlFormat$ (added in v4.801)

Returns the default format used for creating HTML tags. Possible values are: Uppercase, Lowercase, XHTML.

^$GetHtmlTagAttr("TagStr";Attr[;Format])$ (added in v4.8)

Returns the value of the specified HTML attribute. If the Format parameter is not specified, the result is determined by the settings in NoteTab's Options. Use the Format parameter to control the case of minimized attributes (it has no effect on the value returned for normal attributes). It can have one of the following values: UPPERCASE, LOWERCASE, or XHTML. Example:

^$GetHtmlTagAttr("<DL COMPACT>;Compact;XHTML)$ -> compact

^$GetHtmlTagAttr("<DL COMPACT>;Compact;UPPERCASE)$ -> COMPACT

^$GetHtmlTagAttr("<TD ALIGN="left" WIDTH="250">";Width)$ -> 250

^$GetHtmlTagName("TagStr"[;Format])$ (added in v4.8)

Returns the name of the HTML Tag, either in uppercase or lowercase. If the Format parameter is not specified, the character case is determined by the settings in NoteTab's Options. Use the Format parameter to control the format of HTML tags. It can have one of the following values: UPPERCASE, LOWERCASE, or XHTML. Example:

^$GetHtmlTagName("<TD ALIGN="left" WIDTH="250">";LOWERCASE)$ -> td

^$GetHtmlTagTidy("TagStr"[;Format])$ (added in v4.8)

Returns a properly formatted HTML tag converted to uppercase, lowercase, or XHTML format. If the Format parameter is not specified, the result is determined by the settings in NoteTab's Options. Use the Format parameter to control the format of HTML tags. It can have one of the following values:

UPPERCASE, LOWERCASE, or XHTML. Example:

^$GetHtmlTagTidy("<HR SIZE=2 NOSHADE>";XHTML)$ -> <hr size="2" noshade="noshade" />

^$GetHtmlTextTidy("Str"[;Format])$ (added in v4.8)

Returns the string with HTML tags converted to Uppercase, Lowercase, or XHTML format. If the Format parameter is not specified, the result is determined by the settings in NoteTab's Options. Use the Format parameter to control the format of HTML tags. It can have one of the following values: UPPERCASE, LOWERCASE, or XHTML.

^$GetTidyExe$ (added in v4.8)

Returns full path and name of HTML Tidy application.

^$StrToHtml("Str"[;ConvertLineBreaks[;ConvertEntities]])$ (added in v4.83)

Converts plain text to HTML format. "Str" represents the text you want to convert. Use False for ConvertEntities if you don't want special characters (e.g. ©) to be converted to HTML entities (e.g. &copy;); the default value when omitted is True. Use False for ConvertLineBreaks if you don't want <p> and <br> tags to be inserted at line breaks in the text; the default value when omitted is True. Note that entities are determined based on the standard ANSI character set.

TopStyle

NoteTab now supports Bradsoft's TopStyle CSS editor, version 1.51 and above -- a program for editing Cascading Style Sheets. You can learn more about this useful program and download the latest version by visiting the following Web page:

http://www.bradsoft.com/redir.asp?id=130

Note that the TopStyle commands described below are used in the TopStyle library packaged with NoteTab. There is also a convenient TopStyle Clipbar to access the Clip commands.

^!EditStyleSheet [FileName] (added in v4.8)

Opens the specified style sheet file in TopStyle. If no file name is specified, this command will launch TopStyle without opening a specific style sheet. Note that unlike the EditStyleBlock and EditStyleAttr functions, which block the calling application until the user closes TopStyle, EditStyle Sheet simply executes TopStyle and returns immediately.

^$EditStyleBlock("Str")$ (added in v4.8)

Opens TopStyle in <style>..</style> block editing mode. Returns the updated style block. Note that the "Str" argument should not include the surrounding <style>..</style> tags.

^$EditStyleAttr("Str")$ (added in v4.8)

Opens TopStyle in inline (STYLE attribute) editing mode. Returns the updated style. Note that the contents of the style attribute should only include the value assigned to the style attribute. For example, if you wish to edit the style attribute in the tag <span style="color:blue">, then you should only pass color:blue to this function.

^$IsTopStyleEnabled$ (added in v4.8)

Returns 1 if the TopStyle editor is available through NoteTab, and 0 if it is not.


Select, Copy, and Insert Text

Use the following commands and functions to select text in the editor, move or retrieve the cursor position, copy text to a variable, and insert or paste text into NoteTab or another application. See also Clipboard Copy / Paste, Find / Replace, and Keyboard Macros for related topics.

Commands:

^!ClearBookmarks

Only NoteTab Pro: clears all bookmarks.

^!GoToBookmark n

Only NoteTab Pro: moves the cursor to the specified bookmark. "n" should be a value between 0 and 9.

^!InsertCode Any text (added in v4.84)

Similar to ^!InsertText, except that the value is inserted without interpreting ^?{} prompts and Clip tokens like ^P, ^T, ^&, ^#, etc. However, variables and functions used in the specified value are evaluated normally.

^!InsertFile FileName

Inserts the content of the specified file "FileName" at the cursor position.

^!InsertSelect Any text with tokens (^p/^t) (added in v4.9)

Inserts the text following the command into the document and selects it. Since the text must hold on the same line as the command, you will have to use the ^p token to indicate line breaks.

^!InsertText Any text with tokens (^p/^t)

Inserts the text following the command into the document. Since the text must hold on the same line as the command, you will have to use the ^p token to indicate line breaks. Since version 4.8, this command is sensitive to the "Indent on Paste" setting in the Options dialog box on the Clipbook tab. Inserted text remains selected when the ^& token is used to add text to the criteria. You can precede it with the command

^!SetPasteIndent Off

to make it ignore the indent setting.

^!Jump nnn

or

^!Jump +/-nnn

or

^!Jump [LINE_START|LINE_END][SELECT_START|SELECT_END][TEXT_START|TEXT_END]

Moves cursor to the indicated position. If the parameter is a number without a sign (+/-), the command will treat it as the line position from the start of the document. When a sign is used, the command will move the cursor a relative number of lines from the current position; a positive number moving it towards the end of the text and a negative number towards the start. If you don't specify a line number, you can use one of the following settings:

LINE_START or LINE_END: places cursor at the beginning or end of the current line. This feature treats a line as if word wrap is turned off.

SELECT_START or SELECT_END: places cursor at the beginning or end of the selection and unselects the text.

TEXT_START or TEXT_END: moves to start or end of a plain document or the content of an Outline heading.

DOC_START or DOC_END: moves to start or end of any kind of document.

^!MoveCursor +/-nnn

Moves relative position of cursor in document by nnn steps. A positive value moves the cursor towards the end of the document and a negative value towards the start. Note that a line break represents two characters.

^!Select nnn

or

^!Select +/-nnn

or

^!Select [WORD(s)][LINE(s)][PARAGRAPH(s)][URL][FILENAME][HYPERLINK][ALL][BOL][EOL]

^!Select [EMAIL][HTMLTAG] (added in v4.8)

Selects text in the document. Since version 4.8, setting the size to 0 removes the selection. If the parameter is a number without a sign (+/-), the command will treat it as the number of lines to select from the cursor position. When a sign is used, the command will increase or decrease the size of the selection (characters) by the amount specified. If you don't specify a size value, you can use one of the following settings:

WORD(s): selects the word at the cursor position. If several words are partially selected, WORDS extends the selection to include a whole word at each end.

LINE(s): selects the line at the cursor position. If several lines are partially selected, LINES extends the selection to include a whole line at each end.

PARAGRAPH(s): selects the paragraph at the cursor position. If several paragraphs are partially selected, PARAGRAPHS extends the selection to include a whole paragraph at each end.

URL: selects a URL at the cursor position, if any.

FILENAME: selects a file name at the cursor position.

HYPERLINK: selects a NoteTab hyperlink at the cursor position.

ALL: selects all the text in the document window.

BOL: extends the selection to the beginning of the line.

EOL: extends the selection to the end of the line.

EMAIL: extends the selection of an e-mail address under the cursor (added in v4.8)

HTMLTAG: selects a complete HTML tag (added in v4.8)

^!SelectTo row:col

Extends the selection from the current cursor position to the coordinates defined by row and col.

^!SetBookmark n

Only NTP: sets a bookmark at the current cursor position. "n" should be a value between 0 and 9.

^!SetCursor Row:Col

Places cursor at specified row and column.

^!SetCursorPara Row:Col

Similar to ^!SetCursor command but treats long word-wrapped lines as single lines. Both functions have the same effect if word wrap is turned off.

^!SetFocus [Clipbook|ClipEdit|Document|Frame1|Frame2|List_Clip|List_Disk|List_Docs|List_Favs|Outline|PasteBoard]

Moves the focus to the specified screen object. This command will fail if the NoteTab window is minimized. Example to move the focus to the Outline-headings window:

^!SetFocus Outline

^!SetPasteIndent [On|Off] (added in v4.8)

Enables or disables automatic indenting when a Clip inserts text into a document. The scope of this command is limited to the Clip (and eventual sub-Clips) where it was invoked. When a Clip ends, the original user setting is automatically re-enabled.

^!SetView RowTop:ColLeft (added in v4.8)

Moves the top line and leftmost column to the specified coordinates in current document window.

Functions:

^$GetBlock$

^$GetBlock[(SelectText)]$ (added in v4.8)

Returns a block of text at cursor position. Similar to ^$GetWord$ but only uses tabs and blank spaces as a delimiter. This function can, for example, retrieve file names, URLs, etc. Version 4.8: added the optional Boolean argument "SelectText" to make NoteTab select the corresponding block of text.

^$GetChar$

or

^$GetChar(Index)$

or

^$GetChar(+/-Index)$

Returns the character at the cursor position if no parameter is specified. If the parameter is used, it returns the character at the position defined by Index. Use a + or - sign to indicate a relative position with respect to the cursor position.

^$GetCol$

Returns column index of cursor in current document. Since v4.6: If some text is selected, then the beginning of the selection determines the column index.

^$GetColEnd$ (added in v4.8)

Returns the cursor column index in the current document. If some text is selected, then the end of the selection determines the column position.

^$GetColLeft$ (added in v4.8)

Returns the leftmost column index visible in current document window.

^$GetColScreen$ (added in v4.6)

Returns the actual column position on the screen. Unlike ^$GetCol$, this function takes into account expanded tabs. This function is only meaningful in NoteTab Pro; NoteTab Light/Std return the same result as the ^$GetCol$ function.

^$GetColStart$ (added in v4.8)

Returns the cursor column index in the current document. If some text is selected, then the beginning of the selection determines the column position.

^$GetHtmlTag[(SelectText)]$ (added in v4.8)

Returns the HTML tag at cursor position. Use the optional Boolean argument "SelectText" to make NoteTab select the corresponding block of text.

^$GetQuoteBlock[(SelectText)]$ (added in v4.8)

Returns the block of text between double quotes (") at the cursor position. Use the optional Boolean argument "SelectText" to make NoteTab select the corresponding block of text. This function is especially useful for retrieving attribute values within HTML tags.

^$GetParaCol$ (added in v5.4)

Returns cursor column position within paragraph in current document.

^$GetParaRow$ (added in v5.4)

Returns paragraph row index of cursor in current document.

^$GetRow$

Returns line index of cursor in current document. Since v4.6: If some text is selected, then the beginning of the selection determines the line index.

^$GetRowEnd$ (added in v4.8)

Returns the cursor line index the in current document. If some text is selected, then the end of the selection determines the line index.

^$GetRowStart$ (added in v4.8)

Returns the cursor line index in the current document. If some text is selected, then the beginning of the selection determines the line index.

^$GetRowTop$ (added in v4.8)

Returns the index of the top line visible in current document window.

^$GetSelection$

Returns the text contained in the document selection.

^$GetSelSize$

Returns size of selection in current document.

^$GetWord$

^$GetWord[(SelectText)]$ (added in v4.8)

Returns the word at cursor position. Version 4.8: added the optional Boolean argument "SelectText" to make NoteTab select the corresponding block of text.

^$IsBookmark(Index)$

Determines if specified bookmark exists in the active document. Returns 1 if the bookmark number is defined and 0 if it is not used.


Clipboard Copy / Paste

Use the following commands and functions to use the Windows Clipboard and exchange text with other applications.

Commands:

^!ClipBoardRestore [+] (added in v4.6)

Restore the contents of clipboard saved through the ^!ClipBoardSave command. Use the optional "+" parameter if you want NoteTab to keep the saved Clipboard data in its internal memory (lets you restore it again at a later stage).

^!ClipBoardSave (added in v4.6)

Saves the Clipboard contents (any type of data) in NoteTab's internal memory. This command is to be used in conjunction with ^!ClipBoardRestore. It is particularly useful when you want to use the Clipboard for temporary storage without permanently removing what the user may have initially stored in it.

^!CopyClip ClipName

Copies the content of a Clip directly into the Clipboard. Clips are not executed through this procedure, so even if the Clip is executable or contains variables, these are not processed and the text is used in its original state.

^!Paste

Inserts the Clipboard contents into the active document.

^!PasteBack

Unlike the "^!Paste" command, which pastes the Clipboard content into the current NoteTab document, "^!PasteBack" attempts to paste into the last control that copied text to the Clipboard (the control is not reset when text is copied through Clip commands). Thanks to this command, you can paste text processed by the Clipbook into practically any active application. Note that this feature is only available in the commercial and trial versions of NoteTab.

^!PasteSelect

Pastes the content of Clipboard into active document and selects the pasted text.

^!SetClipboard Any text with tokens (^p/^t)

Copies the text following the command into the Clipboard. Since the text must hold on the same line as the command, you will have to use the ^p token to indicate line breaks.

^!TypeBack

Similar to PasteBack but inserts text by typing it instead of pasting it. Slower than PasteBack but may work better with some applications.

Functions:

^$GetClipboard$

Returns the text contained in the Clipboard.

^$GetClipboardSize$

Returns the size of text contained in the Clipboard.


 Find / Replace Text

Find / Replace Text

Use the following commands and functions to search or replace text in the active document. Special instructions are also available to search and process fields in delimited (tab, colon, or other) text files.

Commands:

^!Find "SearchText" [Options TCIBGWHORSn]

Searches for the specified text. Tab and line break characters should be replaced by their tokens (^T and ^P respectively). You can use the following optional settings:

T: Does not search for whole words only (search string can be found within longer words).

C: Searches for whole words only.

If the options T or C are not used, NoteTab will search for whole words if the search criteria does not contain spaces or other word delimiting characters. If the search criteria contains such delimiters, then NoteTab will accept matches that are not whole words.

I: Ignores character case.

B: Searches backwards.

G: Global scope; searches through all the open documents.

W: Searches through the whole document (not just from the cursor position).

H: Only searches within selection if text is highlighted (setting ignored if no text selected).

O: Only searches in current outline topic. This option is ignored if the Global scope option "G" is also set (available since v5.7)

R: Specifies that the search criteria represents a regular expression.

S: Silent search. NoteTab will not display any message box.

n: Represents a number between 1 and 9 inclusive. This option is only valid when used with the R option for regexp searches. NoteTab selects the corresponding regexp subpattern. This option was added to NoteTab 5.0.

The following example will find the next occurrence of the word NoteTab starting from the cursor position. If a match is not found in the current document, the other open documents will also be searched:

^!FIND "NoteTab" G

The search criteria must always be placed between double quotes if you don't specify search options.

^!Replace "SearchText" >> "ReplaceText" [Options TCIBGWHORSAn]

or (using tabs, see below)

^!Replace SearchText ReplaceText [Options TCIBGWHORSAn]

Similar to the "^!Find" command but replaces matches with the replace criteria. The first format uses spaces to separate parameters and the second uses a tab character. Use one or the other but do not mix the two formats within an instruction. You can use the following optional setting, which is specific to the Replace command:

A: Use to replace all matched occurrences. When this option is not used, only the first match is replaced.

The following Clip example will search all open documents and replace the listed upper case HTML tags to their lower case equivalent:

^!Replace <B> <b> GA

^!Replace </B> </b> GA

^!Replace <I> <i> GA

^!Replace </i> </i> GA

^!SetDelimiter "Delimiter"

Defines field delimiter used by "GetField" and "GetPosInField" functions.

Functions:

^$GetDocListAll("SearchPattern";"ReplaceString")$ (added in v5.7)

Finds all matching strings in the current document (or selected text) based on the SearchPattern regexp pattern. The function returns a string with each match formatted according to the ReplaceString. See the Substring Replacements page in the separate Regex.chm help file for ReplaceString details.

Example that collects and displays all URLs in a Web page:

^!Info [L]^$GetDocListAll("(?s)<a.+?href\s*?=\s*?"(.*?)"";"$1\r\n")$

^$GetDocMatchAll("Pattern"[;SubPatternId])$ (added in v5.0)

Finds all matching strings based on the supplied regexp pattern. Optionally specify a subpattern value between 1 and 65536. Use the ^!SetListDelimiter command to define how matches are separated in the resulting string.

Example that collects all URLs in a Web page:

^!Set %NewVariable%=^$GetDocMatchAll("(?s)<a.+?href\s*?=\s*?"(.*?)"";1)$

^$GetDocReplaceAll("SearchPattern";"ReplaceString")$ (added in v5.7)

The function returns a string containing all text in the current document (or selected text) matching the SearchPattern regexp pattern replaced with text specified by ReplaceString. See the Substring Replacements page in the separate Regex.chm help file for ReplaceString details.

Example that replaces all h2 tags to h3:

^!Info [L]^$GetDocReplaceAll("<h2>(.*)</h2>";"<h3>$1</h3>")$

^$GetReSubStrings$ (added in v5.0)

The above function is best used together with ^!SetArray. It extracts all Substrings from a regexp search after using ^!Find. Use the ^!SetListDelimiter command to define how matches are separated in the resulting string. Example:

^!SetArray %Array%=^$GetReSubStrings$

^$GetRegexErrorMsg$ (added in v5.0)

Returns the error text if the previous regex pattern contained mistakes. If there was no error, the function returns an empty string.

^$GetField(Row;Col)$

Returns the field text found at the specified row and data column in a delimited file. Set Row to -1 to indicate the current line.

^$GetPosInField(Row;Col;Options;"SearchCriteria")$

Returns the position of a search criteria in the specified field in a delimited text. No match returns 0. You can use the following optional settings:

T: Does not search for words only (search string can be found within longer words)

I: Ignore character case

W: Criteria must match whole field

S: Criteria must be at start of field


Document Processing

Various commands and functions to process the text in a document.

Commands:

^!AddHeading "HeadingName"

Adds a new heading to the active Outline document.

^!DeleteLine

Deletes the current line.

^!InsertFile FileName

Inserts the content of the specified file "FileName" at the cursor position.

^!SetColumnWrap nn

Defines the column position for word wrap. nn is the value in number of characters.

^!SetWordWrap ON/OFF (added in v4.51)

Changes word wrap mode in active document.

^!UpdateColumnWrap

NTS only. Reformats the text to fit within the defined column wrap. This command has no effect in NoteTab Pro.

Functions:

^$GetLine$

or

^$GetLine(Index)$

or

^$GetLine(+/-Index)$

Returns the text contained in the specified line. The "Index" parameter is optional. When it is not used, this function refers to the line where the cursor is placed; otherwise it refers to the line position from the start of the document. By preceding the number with a + or - sign, the Index value refers to the relative line position with respect to the current line (e.g. ^$GetLine(-1)$ refers to the previous line).

^$GetLineCount$

Returns total number of lines in the current document. This count is affected by the word-wrap status. The last line is considered to follow the last new line ("Enter") character, even if this line contains no characters. Or think of it as the total number of rows in the editor window.

^$GetLineSize$

or

^$GetLineSize(Index)$

or

^$GetLineSize(+/-Index)$

Returns the size of the text contained in the specified line. The "Index" parameter is optional. When it is not used, this function refers to the line where the cursor is placed; otherwise it refers to the line position from the start of the document. By preceding the number with a + or - sign, the Index value refers to the relative position with respect to the current line (e.g. ^$GetLineSize(+1)$ refers to the size of the next line).

^$GetParaCount$

Returns total number of paragraphs in the current document. In this context, a paragraph is defined as a sequence of characters terminated by a new line character. (New line characters are what is inserted when you press the "Enter" key in a document.) NoteTab's "paragraphs" are what many other programs call "lines". The GetParaCount command is not affected by the word-wrap status. When word-wrap is turned off, GetParaCount works the same as GetLineCount.

^$GetParagraph$ (added in v4.6)

or

^$GetParagraph(Index)$ (added in v4.6)

or

^$GetParagraph(+/-Index)$ (added in v4.6)

Returns the text contained in the specified paragraph (=single word-wrapped line). The "Index" parameter is optional. When it is not used, this function refers to the paragraph where the cursor is placed, otherwise it refers to the paragraph position from the start of the document. By preceding the number with a + or - sign, the Index value refers to the relative position with respect to the current paragraph (e.g. ^$GetParagraph(-1)$ refers to the previous paragraph).

^$GetText$

Returns the whole text contained in the active document.

^$GetTextSize$

Returns the text size of the current document.

^$GetTextLineCount$

Similar to ^$GetParaCount$, but if the last character in the file is a new line it will not count the empty space after it as a line, the way that GetParaCount does. (A new line is what you get when you press "Enter" in a document. NoteTab's ^P token represents this.) That is, new line characters are considered by GetTextLineCount to merely terminate the current line. This gives a result that agrees with many other utilities, especially those used on UNIX systems.


Document Management

Use the following commands and functions to manage the documents in NoteTab.

Commands:

^!Close [ALL,SAVE|DISCARD]

or

^!Close "DocumentName" [SAVE|DISCARD]

Closes the specified document(s). If SAVE is specified, a modified document will be saved without prompting (unless it has never been saved before). If DISCARD is specified, modified files are closed without prompting or saving. The ALL parameter can be used together with either SAVE or DISCARD. Options should be separated by a comma or a semicolon, and no spaces; For example: ^!Close ALL,SAVE

^!DestroyDoc [DocumentName]

Closes the current document or the specified document without prompting and deletes the corresponding file from disk if it exists (the file is actually sent to the recycle bin).

^!DirectPrint "Title" Data (added in v4.8)

Prints text directly to the printer, bypassing NoteTab's print procedure. Uses default printer settings. Title is the text shown in the Print manager and Data is the text to send directly to the printer. Data can contain printer control codes.

^!Document [FIRST|LAST|NEXT|PREV]

Selects the specified document tab.

^!FocusDoc

Moves the input focus to the active document.

^!LoadEbcdicCharTable FileName (added in v4.6)

Loads the specified file containing the EBCDIC character tables for conversion to and from Windows ANSI. The NoteTab program path is added if you do not specify a fully qualified path name. The extension .ebc is added if you do not specify a filename extension. You can reset the default character table by specifying the Default.ebc file.

^!Open "FileName" [/R] [/J=nnn]

or

^!Open "File1";"File2";"File3" (added in v4.6)

Opens or selects the specified document "FileName", or opens multiple files (names separated by semicolon). Use fully qualified file names (with path name) to ensure the command finds the correct file. You can use wild cards with this command. The optional switch /R can be used to open the file(s) as Read-Only, and the /J= switch can be used to place the cursor at a specific line number when it is opened. If /J=-1, the cursor will be placed at the beginning of the last line.

^!OpenAscii FileName (added in v4.6)

or

^!OpenAscii FileName1;FileName2;FileName3 (added in v4.6)

Opens and translates the text from ASCII format to ANSI, or selects the specified document "FileName". You can use wild cards with this command.

^!OpenEbcdic FileName [/W=nnn] (added in v4.6)

or

^!OpenEbcdic FileName1;FileName2;FileName3 (added in v4.6)

Opens and translates the text from EBCDIC format to ANSI, or selects the specified document "FileName". You can use wild cards with this command. The optional parameter "/W=nnn" can be used to define a line length for fixed-width EBCDIC files. "nnn" represents the width in characters; a value of 0 indicates variable line lengths delimited with carriage returns. Example: ^!OpenEbcdic /W=132

^!OpenFavorites CategoryName (added in v4.52)

Opens all the documents listed in the specified Favorites list. CategoryName should be specified without a path name or extension.

^!OpenReadOnly FileName (added in v4.6)

Opens or selects the specified document "FileName". You can use wild cards with this command. Newly opened files are set as Read-Only.

^!Print [ALL]

Prints the active document. If the optional parameter "ALL" is used, all the open documents are printed.

^!RenameDoc NewName (added in v4.6)

Renames the active document. The disk file is also renamed if it exists.

^!Save [AS|ALL]

or

^!Save AS FileName

Saves the active document. If the optional parameter "AS" is used, the "Save As" dialog box is displayed. If the optional parameter "ALL" is used, all the modified documents are saved. You cannot use both parameters together. If you specify a file name after the "Save AS" element, the Save As dialog box is not displayed and the specified file name is used.

The following Clip example will save the changes made to the active document:

^!Save

The next example will save all modified documents:

^!Save ALL

The following Clip example will save the active document as a new file called Temp.txt:

^!Save AS c:\My Documents\Temp.txt

^!SaveAscii FileName (added in v4.6)

Similar to the ^!Save command (and accepts the same parameters) but saves the document using the DOS extended ASCII character set instead of Windows ANSI.

^!SaveEbcdic FileName [/W=nnn] (added in v4.6)

Similar to the ^!Save command (and accepts the same parameters) but saves the document in EBCDIC format. The optional parameter "/W=nnn" can be used to define a line length for fixed-width EBCDIC files. "nnn" represents the width in characters; a value of 0 indicates variable line lengths delimited with carriage returns. Example: ^!SaveEbcdic /W=132

^!SaveFavorites CategoryName (added in v4.52)

Adds all the currently open document names to the specified Favorites list. The Favorites category is created if it doesn't exist. CategoryName should be specified without a path name or extension.

^!SetDocIndex IndexValue

Activates the document at the specified position in the tab bar. First document is 1.

^!SetNameFormat Mask (added in v4.6)

The name format is used when new documents are created. The code "%d" indicates where the incremental numbering is inserted in the name. In the following example, the "0.2" between the % and d tells NoteTab to format numbers smaller than 2 digits with leading zeroes: NoName%0.2d.txt

^!SetTopicIndex IndexValue

Activates the topic at the specified position in the current outline document. First topic is 1.

^!ShowHeadings [True|False] (added in v4.52)

Shows or hides Outline heading names in the editor window.

Functions:

^$GetDocCount$

Returns the number of open documents in editor.

^$GetDocName$

^$GetDocName(Index)$ (added in v4.52)

Returns the active document name, if no index is specified, or the document name at specified index position. An invalid index number returns an empty string. The first document is at index 1.

^$GetDocIndex$

^$GetDocIndex(Name)$

Returns the index position of the active document, or the document refered by the Name parameter.

^$GetNameFormat$ (added in v4.6)

This function returns the current new document name format.

^$GetPasteBoardIndex$

Returns the index position of the PasteBoard document. Returns 0 if there is no PasteBoard document.

^$GetSecondWindowIndex$

Returns the index position of document in second window. Returns 0 if there is no second window.

^$GetTopicCount$

Returns number of topics in the current outline document.

^$GetTopicIndex$

^$GetTopicIndex(Name)$ (added in v4.51)

Returns the index position of current outline topic. Use the optional Name parameter to find the index position of another topic.

^$GetTopicName$

^$GetTopicName(Index)$ (added in v4.52)

Returns the current outline heading name, if no index is specified, or the heading name at specified index position. An invalid index number returns an empty string. The first heading is index 1.

^$IsShowHeadings$ (added in v4.52)

Returns 1 if headings are displayed in the outline document window and 0 if they are not.


Outline Documents

Except for ^!CreateOutline, all the following commands and functions will fail unless the active document is an Outline. Note that commands which modify the Outline document will not work in NoteTab Light, unless it is running in trial mode.

Commands:

^!AddHeading "HeadingName"

Adds a new heading to the active Outline document.

^!CreateOutline FileName (added in v5.7)

Creates a new Outline file and saves it with a filename based on the command argument.

^!SetTopicIndex IndexValue

Activates the topic at the specified position in the active Outline document. First topic is 1.

^!ShowHeadings [True|False] (added in v4.52)

Shows or hides Outline heading names in the editor window.

^!TopicAdd "TopicName" AnyText (added in v5.7)

Adds a topic to the active Outline document. The topic name is taken from the TopicName argument and text specified by the AnyText argument is stored in the topic.

^!TopicDelete TopicIndex (added in v5.7)

^!TopicDelete TopicName (added in v5.7)

Deletes the specified topic from the active Outline document. You can either specify the topic name or its position in the list – 1 being the first topic.

^!TopicMove TopicToMove TargetPosition (added in v5.7)

Moves a topic to the specified position. The TopicToMove and TargetPosition arguments can either represent a topic name (surround with double quotes if name contains spaces) or its position in the list – 1 being the first topic. Examples:

^!TopicMove "Topic Name #3" "Topic Name #7"

^!TopicMove 3 7

^!TopicReplace "TopicName" AnyText (added in v5.7)

^!TopicReplace TopicIndex AnyText (added in v5.7)

Replaces data in the specified topic from the active Outline document with text specified by the AnyText argument. You can either specify the topic name (surround with double quotes if name contains spaces) or its position in the list – 1 being the first topic.

^!TopicShow "TopicName" (added in v5.7)

^!TopicShow TopicIndex (added in v5.7)

Displays the specified topic in the active Outline document. You can either specify the topic name or its position in the list – 1 being the first topic.

Functions:

^$GetTopicCount$

Returns number of topics in the current Outline document.

^$GetTopicHeading(TopicIndex)$ (added in v5.7)

Returns the topic name at the specified position in the active Outline document – 1 being the first topic.

^$GetTopicIndex$

^$GetTopicIndex(TopicName)$ (added in v4.51)

Returns the index position of active Outline topic. Use the optional TopicName parameter to find the index position of another topic.

^$GetTopicName$

^$GetTopicName(Index)$ (added in v4.52)

Returns the current outline heading name, if no index is specified, or the heading name at specified index position. An invalid index number returns an empty string. The first heading is index 1.

^$GetTopicText(TopicIndex)$ (added in v5.7)

^$GetTopicText(TopicName)$ (added in v5.7)

Returns the text from the corresponding topic in the active Outline document. You can either specify the topic name or its position in the list – 1 being the first topic.

^$IsShowHeadings$ (added in v4.52)

Returns 1 if headings are displayed in the Outline document window and 0 if they are not.


Printing Text

Use the following commands to print the current document or text specified through the argument.

Commands:

^!DirectPrint "Title" Data (added in v4.8)

Prints text directly to the printer, bypassing NoteTab's print procedure. Uses default printer settings. Title is the text shown in the Print manager and Data is the text to send directly to the printer. Data can contain printer control codes.

^!Print [ALL]

Prints the active document. If the optional parameter "ALL" is used, all the open documents are printed.

^!PrintDialog AnyText (added in v5.7)

Displays the Print dialog box so that you can select a printer and modify certain options before starting the print job based on the AnyText argument. If you leave out the argument or AnyText is empty, then the current document text will be printed.

^!PrintPreview AnyText (added in v5.7)

Sends the text from the AnyText argument to the Print Preview window. You can then decide whether to start the print job or cancel the procedure. If you leave out the argument or AnyText is empty, then the current document text will be printed. The following example shows selected text in the preview window:

^!PrintPreview ^$GetSelection$

^!PrintText AnyText (added in v5.7)

Sends the text from the AnyText argument directly to printer using current default settings. The Print dialog box is not displayed. If you leave out the argument or AnyText is empty, then the current document text will be printed.


Disk Files

Use the following commands and functions to manage disk files from NoteTab. Use fully qualified file names (with path name) to ensure the commands and functions find the correct file. See also Disk Directories for related commands.

Beginning with NoteTab version 5.7, you can use tokens for common file and folder names. For details, view Folder and File Tokens in the Main Help File.

Commands:

^!AppendTextToUnicodeFile "FileName" AnyText (added in v4.82)

Appends the specified text to the end of a disk file in Unicode format using the current Windows code page. A new file is created if FileName does not exist.

^!AppendToFile "FileName" AnyText

Appends the specified text to the end of a disk file. A new file is created if FileName does not exist.

^!CloseFileFind

Optional command to close the list of files created with the GetFileFirst function. It is recommended to use this command when you have finished using the list of files as it releases system resources.

^!CopyFile "FileSpecs" "Destination"

Copies the specified file(s) (wildcards can be used) to another directory. Use double quotes around the file names if they contain spaces. If no wildcards are used and the destination file exists, it is sent to the recycle bin before being replaced by the new file.

^!DeleteFile FileSpecs

Deletes the specified file(s) (wildcards can be used) from the disk.

^!Export "FileName" [ASCII|ANSI][MAC|UNIX][SELECTION|ALL][HARDBREAKS]

or

^!Export "FileName" [EBCDIC][SELECTION|ALL][LRECL=nnn] (added in v4.6)

Exports current document under specified file name. Optional settings are used to define output format. Use a comma or colon to separate multiple settings and use double quotes around the file name if it contain spaces. When creating EBCDIC files, you can optionally define a record length (for fixed-width lines) by using the LRECL parameter followed by an equal sign and the width value.

^!IfFileAttr "FileName" Attr GoToLabelTrue [ELSE GoToLabelFalse] (added in v4.8)

Compares FileName attributes with Attr. If Attr is equal or a subset of FileName's attributes, then GoToLabelTrue is activated. Attr can represent multiple values: A = Archive, D = Directory, H = Hidden, R = Read-only, S = System, V = VolumeID, * = All attributes. Example:

^!IfFileAttr "c:\Scandisk.log" AH LabelTrue ELSE LabelFalse

If Scandisk.log has at least the Archive and Hidden attributes set, then the instruction jumps to LabelTrue.

^!IfFileUnicode "FileName" GoToLabelTrue [ELSE GoToLabelFalse]

Jumps to specified label if FileName is a Unicode text file or UTF-8 Web page.

^!FileScramble "InputName"[ "OutputName"[ "Key"]] (added in v4.84)

encrypts and decrypts files. Requires the ntb_enc.dll file. This command can automatically detect if the file needs encrypting or decrypting. InputName is the file to encrypt or decrypt. Use the optional OutputName to define the name of the file created by the operation. If the file is going to be encrypted and you don't specify an output name, the name will be based on InputName with the extension ".npw". If the file is going to be decrypted and you don't specify an output name, the original file name will be used. Use the optional "Key" parameter to define an encryption password (max. 255 characters). Make sure you don't forget your password, or you will not be able to restore your encrypted data.

The encryption method is based on the ARC4 (Alleged RC4) algorithm. The Algorithm known as "RC4" is a trademark of RSA Security, Inc. You should not rely on this feature to protect very sensitive data.

^!MoveFile "FileSpecs" "Destination"

Moves the specified file(s) (wildcards can be used) to another directory. Use double quotes around the file names if they contain spaces.

^!RecycleFile FileSpecs

Moves the specified file(s) (wildcards can be used) to the recycle bin.

^!Refresh

Use this command after file management actions to update the list of available Clipbook libraries and the contents of the Quick List tool. It also checks if any of the open documents were changed on disk.

^!RenameFile "OldName" "NewName"

Renames the specified file (no wildcards allowed). Use double quotes around the file names if they contain spaces.

^!SetFileAttr "FileSpecs" Attr (added in v4.8)

Changes the file attributes. FileSpecs is the file name, which may have wild cards. Attr can represent multiple values: A = Archive, H = Hidden, R = Read-only, S = System, * = All attributes. Use a minus sign in front of the letter to remove an attribute. The following example sets the Archive attribute and removes the Read-only attribute, if set:

^!SetFileAttr "c:\Scandisk.log" A-R

^!TextToFile "FileName" AnyText

Creates a disk file containing the specified text. If a file with such a name already exists on disk, it will be replaced by the new file.

^!TextToUnicodeFile "FileName" AnyText (added in v4.82)

Saves the specified text to FileName in the Unicode format using the current Windows code page.

^!UUDecode "InputName"[ "OutputName"] (added in v4.84)

InputName is the file to decode. Use the optional OutputName to define the name of the UUEncoded data file. If you don't specify an output name, the name stored in the encoded file will be used.

^!UUEncode "InputName"[ "OutputName"] (added in v4.84)

InputName is the file to encode. Use the optional OutputName to define the name of the UUEncoded data file. If you don't specify an output name, the name will be based on InputName with the extension ".uue".

Functions:

^$ChangeFileExt("FileName";"Ext")$ (added in v4.84)

Use this function to create a new file name based on the provided extension. Example:

^$ChangeFileExt("c:\config.sys";"bak")$ = c:\config.bak

^$FileToUrl("FileName")$ (added in v4.8)

Converts a Windows file name to a URL file name. Example:

^$FileToUrl("c:\program files\index.htm")$ -> file:///c|/program%20files/index.htm

^$GetCrcFile("Filename")$ (added in v4.84)

Returns the CRC32 (cyclic redundancy check) value of the specified file. Example:

^$GetCrcFile("^$GetAppFileName$")$

^$GetExpandedName(FileName;BaseDir)$ (added in v4.8)

Returns the fully qualified name of FileName against BaseDir. If BaseDir is not defined, the active document path is used as the reference directory. Example:

^$GetExpandedName(..\MyFile.txt;c:\temp\test\)$ -> c:\temp\MyFile.txt

^$GetExt(FileName)$

Returns the extension of FileName (with extension dot).

^$GetFileAttr(FileName)$ (added in v4.8)

Returns the file attributes as a string of characters. A file can have zero, one, or several attributes. The string may contain the following characters: A = Archive, D = Directory, H = Hidden, R = Read-only, S = System, V = VolumeID, * = All attributes. Example:

^$GetFileAttr(c:\Scandisk.log)$ -> AH

^$GetFileDate(FileName)$

Returns the file date as yyyymmdd. Returns 0 if file does not exist.

^$GetFileFirst(FilePath;FileSpecs[;SortingOrder])$

^$GetFileFirst(FilePath;FileSpecs[;Attr][;SortingOrder])$ (added in v4.8)

^$GetFileFirst([+]FilePath;FileSpecs[;Attr][;SortingOrder])$ (added in v4.83)

Returns the first file name in the list generated by the function. FilePath indicates the directory you want to search and FileSpecs the specs to match the files. FileSpecs can contain the standard wildcards * and ?, and you can specify several criteria separated by a semicolon (;). You must use double-quotes around the FileSpecs parameter if you specify several criteria. The third parameter, SortingOrder, is optional and can be used to specify a sorting order that is different from the default which is file names sorted in alphabetical order. You can use the following values for SortingOrder:

UNSORTED: No sorting is used.

NAME: Files are sorted by name.

TYPE: Files are sorted by type (based on the extension).

DATE: Files are sorted by date.

SIZE: Files are sorted by size.

Use the prefix "REV" to reverse the sorting order (e.g. REVSIZE starts with the largest file).

Version 4.8: added optional Attr parameter. Attr can represent multiple values: A = Archive, H = Hidden, R = Read-only, S = System, * = All attributes. If the Attr parameter is not used, then file attributes are ignored.

Version 4.83: When the Attr field is used, only files that use the specified attributes are selected. To select files that have no attribute settings, use "-" as a value for Attr. You can also span through subdirectories by adding a + sign in front of the FilePath criteria.

^$GetFileName(FileName)$

Returns the name and extension of FileName (without path). Since version 4.8, this function works both on Windows file names and URLs.

^$GetFileNext$

Returns the next file name in the list. If there are no more files, then the result is an empty string.

^$GetFiles(FilePath;FileSpecs[;Attr][;SortingOrder])$ (added in v4.8)

^$GetFiles([+]FilePath;FileSpecs[;Attr][;SortingOrder])$ (added in v4.83)

The parameters are identical to the ^$GetFileFirst$ function. Returns all matching files as a single string using a blank space separator, or the one defined by ^!SetListDelimiter. Note that ^$GetFileNext$ and ^!CloseFileFind do not work with this function. This new function is useful to assign the result to an array variable. Example:

^!SetArray %Files%=^$GetFiles("c:\Program Files\NoteTab Pro\Documents";*.txt;AR;DATE)$

Version 4.83: When the Attr field is used, only files that use the specified attributes are selected. To select files that have no attribute settings, use "-" as a value for Attr. You can also span through subdirectories by adding a + sign in front of the FilePath criteria. The following example will select all files under Windows and its subdirectories, that have the System attribute set:

^$GetFiles("+C:\Windows";*.*;S;Name)$

^$GetFileSize(FileName)$

Returns the size of FileName.

^$GetFileText(FileName)$

Returns the content of the specified file. The value is an empty string if the file does not exist.

^$GetFileTime(FileName)$

Returns the file time as hhnnss. The value is 0 if file does not exist.

^$GetImgHeight(FileName)$

Returns the height in pixels of the specified image file (.gif, .png, .jpg, .bmp). The value is 0 if file does not exist or is not an image.

^$GetImgWidth(FileName)$

Returns the width in pixels of the specified image file (.gif, .png, .jpg, .bmp). The value is 0 if file does not exist or is not an image.

^$GetMD5File("Filename")$ (added in v4.84)

Returns the MD5 signature of the specified file. The result is produced in hexadecimal format. MD5 is a hashing algorithm that generates a digital signature, or Message Digest, representing the supplied data. The MD5 algorithm was produced by RSA Data Security Inc. Example:

^$GetMD5File("^$GetAppFileName$")$

^$GetName(FileName)$

Returns the name of FileName (without path or file extension). Since version 4.8, this function works both on Windows file names and URLs.

^$GetPath(FileName)$

Returns the path segment of FileName (always ends with backslash). Since version 4.8, this function works both on Windows file names and URLs.

^$GetRelativeName(FileName;BaseDir)$ (added in v4.8)

Returns the relative name of FileName against BaseDir. FileName must include a fully qualified path. Enclose the parameters in quotes if they contain a semicolon in the name. If BaseDir is not defined, the active document path is used as the reference directory. Example:

^$GetRelativeName(c:\temp\test\MyFile.txt;c:\temp\)$ -> test\MyFile.txt

^$GetShort(FileName)$

Returns the DOS short name of FileName.

^$GetTempFile$

Returns a Windows temporary filename which can then be used to store data. This file is automatically deleted when you exit Windows.

^$GetUnicodeFileText("FileName")$ (added in v4.82)

Reads Unicode text from FileName and returns it as normal text based on the current Windows code page.

^$UrlToFile("URL")$ (added in v4.8)

Converts a URL file name to a Windows file name. Example:

^$UrlToFile("file:///c|/program%20files/index.htm")$ -> c:\program files\index.htm


Disk Directories

Use the following commands and functions to manage disk directories from NoteTab. See also Disk Files for related commands.

Beginning with NoteTab version 5.7, you can use tokens for common file and folder names. For details, view Folder and File Tokens in the Main Help File.

Commands:

^!ChDir DirName

This command only affects shell commands and is used to define the default directory used by the launched application.

^!MkDir DirName

Create a new directory with the name specified by DirName.

^!RmDir DirName

Deletes the specified directory from the disk. This function will fail if the directory is not empty.

Functions:

^$GetAppPath$

Returns the NoteTab application path (always ends with backslash).

^$GetDataPath$ (added in v5.0)

Returns the folder where NoteTab stores user settings and data (always ends with backslash).

^$GetDocumentPath$

Returns the path for NoteTab document files (always ends with backslash).

^$GetFavoritePath$

Returns the path for NoteTab "favorites" files (always ends with backslash).

^$GetLibraryPath$

^$GetLibraryPath(LibraryName)$ (added in v5.0)

Returns the path for NoteTab Clipbook library files (always ends with backslash).

Starting with version 5.0, you can add a library name as an optional parameter, which causes the function to return the location of the specified library. The parameter is ignored in older versions of NoteTab, so the function is fully backwards compatible. The following example returns the location of the current library:

^$GetLibraryPath(^$GetLibraryName$)$

^$GetLibraryUserPath$ (added in v5.0)

Returns the folder where NoteTab stores user-modified Clipbook libraries (always ends with backslash).

^$GetPath(FileName)$

Returns the path segment of FileName (always ends with backslash). Version 4.8: this function works both on Windows file names and URLs.

^$GetSamplesPath$

Returns the path for NoteTab sample files (always ends with backslash).

^$GetScriptPath$

Returns the path for NoteTab script files (e.g. AWK, Perl, etc.; always ends with backslash).

^$GetShellFolder(SystemFolder)$ (added in v4.9)

Returns the path to the specified folder type "SystemFolder". The folder name always ends with a backslash. See below for SystemFolder values and an example for each value of a corresponding path (under Windows 98):

Desktop --> C:\WINDOWS\Desktop\

Templates --> C:\WINDOWS\ShellNew\

AppData --> C:\WINDOWS\Application Data\

Start Menu --> C:\WINDOWS\Start Menu\

Programs --> C:\WINDOWS\Start Menu\Programs\

Startup --> C:\WINDOWS\Start Menu\Programs\StartUp\

Fonts --> C:\WINDOWS\Fonts\

SendTo --> C:\WINDOWS\SendTo\

Recent --> C:\WINDOWS\Recent\

Favorites --> C:\WINDOWS\Favorites\

NetHood --> C:\WINDOWS\NetHood\

Personal --> C:\WINDOWS\My Documents\

Cache --> C:\WINDOWS\Temporary Internet Files\

Cookies --> C:\WINDOWS\Cookies\

History --> C:\WINDOWS\History\

PrintHood --> C:\WINDOWS\PrintHood\

Local AppData --> C:\WINDOWS\Local Settings\Application Data\

My Pictures --> C:\WINDOWS\My Documents\My Pictures\

Administrative Tools -->

C:\WINDOWS\Start Menu\Programs\Administrative Tools\

^$GetShort(FileName)$

Returns the DOS short name of FileName.

^$GetSoundPath$

Returns the path for NoteTab sound files (always ends with backslash).

^$GetSpecialPath(TypeFolder)$ (added in v4.8)

Returns the path name of the specified Windows folder. TypeFolder can have one of the following values:

AppFolder

Desktop

DesktopDir

StartMenu

Programs

Startup

SendTo

Favorites

Recent

CommonDesktopDir

CommonStartMenu

CommonPrograms

CommonStartup

CommonFavorites

^$GetSysPath$

Returns the Windows System path (always ends with backslash).

^$GetSysProgPath$ (added in v4.82)

Returns the path containing system programs like MS-Notepad and FTP.exe. By default, the path is "c:\WINDOWS\" under Windows 95 and 98, and "c:\WINNT\System32\" under Windows NT.

^$GetTemplatePath$

Returns the path for NoteTab template files (always ends with backslash).

^$GetTmpPath$

Returns the Windows temporary path (always ends with backslash).

^$GetWinPath$

Returns the Windows path (always ends with backslash).


Executing Programs

Use the following commands and functions to execute external programs and minimize/restore the NoteTab window. See also Disk Directories for related commands.

Commands:

^!ActivateApp

Activates the NoteTab application Window. If NoteTab is minimized or behind other windows, the window is restored and brought to the front.

^!ChDir DirName

This command only affects shell commands and is used to define the default directory used by the launched application.

^!CmdShow [Normal|Minimize|Maximize]

Use this command to display the next program to be launched through the Clipbook minimized/maximized. The following values can be used:

Normal: Program is launched using the default window style.

Minimize: Program is launched minimized.

Maximize: Program is launched maximized.

^!CommandLine

Executes the specified program command unless it represents a Clip command. See also the new ^!Shell command below.

^!Dos DosCommand

Executes the specified Dos-shell command or program. The Dos window is closed when the command or program has finished executing. Example: ^!Dos dir *.*

^!Email Address;Subject[;+]

or

^!Email Address;Subject;MessageText (added in v4.6)

Creates a new e-mail message. The e-mail address and subject should be separated by a semicolon (;). The third parameter with the "+" is optional. When used, it tells the Clipbook that the content of the current document should be used for the body of the message. Since version 4.6, you can include a whole message text after the Subject parameter.

The following Clip example will create a new e-mail message with the address "sales@fookes.com" and the subject "Order for NoteTab Pro":

^!Email sales@fookes.com;Order for NoteTab Pro

The next example will create a new e-mail message with no preset address, the subject "Please check!", and the content of the current document:

^!Email ;Please check!;+

^!FocusApp AppTitle (added in v4.52)

Activates the application window with a title caption that matches the specified text. The error flag is set if no matching window is found. For example, if the Windows calculator utility is open, the following command will bring it to the front:

^!FocusApp Calculator

Most applications usually show other information in the title bar. For these cases, you can use an asterisk "*" either at the beginning or the end of the AppTitle text to specify that the text should match the end or the beginning of the title respectively. For example, MS Wordpad displays the document name in front of the program name, so the following instruction will work if Wordpad is open:

^!FocusApp *WordPad

^!MinimizeApp

Minimizes the NoteTab application Window. This can often make clips run faster. But note that some commands, (such as ^!Keyboard), do not work properly when the editor window is minimized.

^!Run CommandLine

This command is provided for backward compatibility. It can be used to launch other programs. The ^!Wait command does not work with programs launched this way.

^!SetStdErrorName FileName

Defines the default filename for the StdError output generated by console applications. If you don't specify a path, the NoteTab application directory is used.

^!Shell CommandLine (added in v4.82)

Launches the specified file, program, or URL through the Windows shell. Proposed as a replacement for the default "^!" launch method. Example: instead of using "^!WordPad c:\autoexec.bat", use "^!Shell WordPad c:\autoexec.bat"

^!ShellWait CommandLine (added in v4.82)

Similar to the ^!Shell command, but waits until the launched program is terminated before moving to the next Clip instruction. Unlike the ^!Wait command, you can continue editing files in NoteTab while the application is running. Example:

^!ShellWait WordPad c:\autoexec.bat

^!Url <url>

or

^!Url [browser] <url>

Opens the specified URL in the default browser. You can also optionally specify the browser command in square brakets (which are required). The following example will open the Fookes Software Web site in Internet Explorer; the "-nohome" switch is recognized by Internet Explorer and makes it skip the opening of the homepage:

^!Url [iexplore.exe -nohome] www.fookes.com

If you have Netscape 6.x installed on your computer, you can launch it like this:

^!Url [Netscape6] www.fookes.com

You can launch Internet Explorer with [IExplore], Mozilla with [Mozilla], Netscape 4.x with [Netscape], and Opera with [Opera]. For other browsers, you can specify the program name (include the .exe extension and full path if necessary).

^!Wait

This instruction will interrupt Clip execution until the previously launched application has closed. You cannot use the editor when it is in Wait mode (the editor's window caption indicates it is waiting for the application to close). Note that the ^!Wait command may not work with all applications (during testing, it did not work with the MS-Write program).

Functions:

^$GetDosOutput("Command")$

Returns output from DOS command. "Command" represents command to execute. The stderr stream is saved in a file called "StdError.err" in NoteTab's application directory unless another file is specified with the SetStdErrorName command. Prior to version 4.8, this command was only available in the commercial and trial versions of NoteTab.

Example: ^$GetDosOutput(dir c:\*.*)$

^$GetInputOutput("Command")$

Launches the console program specified by "Command" and sends the current document text to the StdInput data stream. The function returns the console's StdOutput data stream. The stderr stream is saved in a file called "StdError.err" in NoteTab's application directory unless another file is specified with the SetStdErrorName command. Prior to version 4.8, this command was only available in the commercial and trial versions of NoteTab.

^$GetOutput("Command")$

Returns the console's output. "Command" represents the command to execute. The stderr stream is saved in a file called "StdError.err" in NoteTab's application directory unless another file is specified with the SetStdErrorName command. Prior to version 4.8, this command was only available in the commercial and trial versions of NoteTab.

Example: ^$GetOutput(cmd.exe /c dir c:\*.*)$


Using Perl, Gawk, and Other Scripts

Use the following commands and functions to execute Perl, Gawk, or other scripts. See also Executing Programs for related commands.

If you don't have a Win32 Perl or Gawk interpreter installed on your computer, there are a number of good ones you can download from the Internet. The following Freeware 32-bit interpreters have been tested with NoteTab and work very well:

For Perl:

http://www.ActiveState.com/pw32/

For Gawk:

http://gnuwin32.sourceforge.net/packages/gawk.htm

All you need to do is install them wherever you want on your hard disk. Then, the first time you try to run a script, NoteTab will prompt you for the file name of the interpreter. NoteTab will only prompt you again if you delete or move the interpreter to another location, or delete the NoteTab INI file.

Scripts need not be stored in Clip libraries; each script may be stored in its own file. Clips which process scripts stored in the Clip library are not Clipbar-safe.

Commands:

^!RunGawk ScriptName

Applies specified GAWK script to selection in current document or whole document. ScriptName can either represent the name of a Clip or a script file. Note that you will have to use a script file if you are going to run this command from the Clipbar. The stderr stream is saved in file called "StdError.err" in NoteTab's application directory unless another file is specified with the SetStdError Name command.

^!RunPerl ScriptName

Applies specified Perl script to selection in current document or whole document. ScriptName can either represent the name of a Clip or a script file. Note that you will have to use a script file if you are going to run this command from the Clipbar. The stderr stream is saved in file called "StdError.err" in NoteTab's application directory unless another file is specified with the SetStdError Name command.

^!RunScript "Command" "ScriptName"

Similar to ^!RunGawk except you must specify the command to execute the console application. The stderr stream is saved in file called "StdError.err" in NoteTab's application directory unless another file is specified with the SetStdErrorName command. Use the code "^1" to indicate where the Script file name should be inserted.

^!SetStdErrorName FileName

Defines the default filename for the StdError output generated by console applications. If you don't specify a path, the NoteTab application directory is used.

Functions:

^$GetGawkExe$

Returns full path and name of GAWK application.

^$GetPerlExe$

Returns full path and name of Perl application.

^$GetStdErrorName$

Returns the current filename for the StdError output generated by console applications.


Using Other Clips

Use the following commands and functions to execute other Clips, retrieve their content, change libraries, etc.

Commands:

^!Clip "ClipName" [Text]

Executes the specified Clip in the current library. Do not attempt to call clip items recursively or NoteTab will freeze in a never-ending loop (if this happens, you can press the Ctrl+Alt keys together to stop the execution). You can insert text in a Clip item by using an optional second parameter – this will make the Clipbook behave in the same way as if that text had been selected in a document. You must place double quotes around the Clip name if you want to specify text criteria or if the Clip name contains one or more blank spaces.

The following example will activate the Clip item called "Explorer":

^!Clip Explorer

If the Clip called Explorer contains the ^& code, the next example will substitute it with the text "C:\Windows":

^!Clip "Explorer" C:\Windows

^!DestroyLibrary [LibraryName] (added in v4.8)

Deletes the specified Clipbook library (path name and extension are not needed). If the optional LibraryName argument is not used, then the library currently running the Clip is closed and destroyed.

^!FarClip LibraryName:ClipName

or

^!FarClip "LibraryName:ClipName" [Text]

Similar to the ^!Clip command but invokes a Clip from a library on disk instead of the active library. Clips invoked through this method are stored in an internal cache memory to improve performance (the cache will reload the Clip to memory if it detects that the Library file has been modified). LibraryName name must be stored in the Libraries folder if you do not specify a path, but does not need to have the .clb extension (you can use a different extension if you do not want the library to be listed in the Clipbook tool or the button bar). This command is particularly useful within specialized Template files. You can also use it to invoke frequently used procedures. Example: ^!FarClip HTML:Center

^!LoadLibrary LibraryName

Loads the specified library into Clipbook.

^!ReloadLibrary (added in v4.52)

Reloads the current Clipbook library. Useful if another application has modified it.

^!SetAutoReplace [ON|OFF] (added in v5.7)

Changes AutoReplace mode accordingly if the Clipbook library is open.

^!ShowClipbook [TRUE|FALSE]

Shows or hides the Clipbook window.

^!TimerPlay ClipName

Assigns the Clip instructions to the timer memory. The instructions remain available even when you change libraries but are cleared when you close the Clipbook.

^!TimerStart nnnn

Defines an event timer. nnnn represents the interval in milliseconds. For example, "^!TimerStart 5000" will execute the assigned Clip (set with "^!TimerPlay") every 5 seconds. Note that the Clip is not executed if the Clipbook is already in the process of executing another Clip.

^!TimerStop

Stops the timer and clears the assigned Clip instructions.

Functions:

^$GetActiveLibraryFileName$ (added in v5.7)

Returns the fully qualified filename of the current open Clipbook library. Similar to ^$GetLibraryFileName$, but return an empty string if the Clipbook panel is closed.

^$GetActiveLibraryName$ (added in v5.7)

Returns the name of the current open Clipbook library. Similar to ^$GetLibraryName$, but return an empty string if the Clipbook panel is closed.

^$GetClipName$ (added in v4.6)

Returns the name of the currently interpreted Clip. This function returns an empty string within Clips run by the timer event and executable templates.

^$GetClipText(ClipName)$

Returns the content of a Clip as text. The specified Clip is not executed when invoked. Note that Clips using this function cannot be run from the Clipbar or the ^!FarClip command.

^$GetClipVersion$

Returns the version of the Clipbook parser. Useful to check for compatibility with Clip instructions. Since version 4.801, this function returns the actual NoteTab release version as an integer. For example, in version 4.801, ^$GetClipVersion$ returns 4801.

^$GetLibraryName$

Returns the name of the current Clipbook library.

^$GetLibraryFileName$ (added in v5.0)

Returns the fully qualified filename of the current Clipbook library.

^$IsAutoReplace$ (added in v5.7)

Returns 1 if the Clipbook library is open in AutoReplace mode, or 0 if it is not.


Clipbars

Use the following commands and functions to control the Clipbar feature (not available in NoteTab Light).

Commands:

^!CloseClipbar (added in v4.8)

Closes the current Clipbar.

^!OpenClipbar Name (added in v4.8)

Opens the specified Clipbar file.

^!ReloadClipbar (added in v4.8)

Reloads the current Clipbar.

Functions:

^$GetClipbarName$ (added in v4.8)

Returns the name of the current Clipbar file.


Menu and Toolbar Commands

Execute any NoteTab menu and toolbar command from a Clip. See also Keyboard Macros for related commands.

^!Menu NameSequence (added in v4.9)

You can use this command to activate any enabled command from the main program menu. The first menu name in the sequence is the one that appears at the top of the main menu, followed by submenu names (if any), and then the name of the final menu item to activate. You must separate submenu items with a forward slash and leave out any ellipsis. You should put double quotes around a menu name if it contains one or more forward slash characters. The case of characters does not have to be the same as the actual menu commands.

The following example opens the Font dialog box for the active document:

^!MENU Document/Font/Change Font

The example below inserts the date and time from the menu command (notice the use of double quotes):

^!MENU Document/"Insert Date/Time"

^!SetShortcut Shortcut NameSequence (added in v4.9)

You can use ^!SetShortcut to temporarily change keyboard shortcuts for any of the main menu items. It takes two parameters, which are separated by a space character. The first parameter represents the shortcut value and the second represents the menu item. The first menu name in the sequence is the one that appears at the top of the main menu, followed by submenu names (if any), and then the name of the final menu item to activate. You must separate submenu items with a forward slash and leave out any ellipsis. You should put double quotes around a menu name if it contains one or more forward slash characters. The case of characters does not have to be the same as the actual menu commands. Note that this command is not available in NoteTab Light.

The two instructions in the following example assign the Ctrl+Shift+F shortcut to the "Change Font" menu command, and Ctrl+T to the "Insert Date/Time" menu command:

^!SetShortcut Ctrl+Shift+F Document/Font/Change Font

^!SetShortcut Ctrl+T Document/"Insert Date/Time"

^!Toolbar ToolTipText

You can execute any NoteTab command that is available in the toolbar (it doesn't matter if the button is displayed in the toolbar or not). You specify the command you want to execute by using the keyword "Toolbar" followed by a space and its tooltip text. The button tooltip text can be seen by placing the mouse cursor over the button. The available commands are also listed in the Clip Assistant. You can check if the command was successfully executed with the ^!IfError command. An error condition is only triggered if the command failed because the button was disabled.

The following example will activate the "Open Document" command:

^!TOOLBAR Open Document

You can of course create a sequence of instructions within a Clip. The next example will create a new document, paste the content of the Clipboard into it, then activate the Save As dialog box:

^!TOOLBAR New Document

^!TOOLBAR Paste

^!TOOLBAR Save As


Keyboard Macros

Use keyboard macros to simulate keys being pressed (either in NoteTab or other applications). See also Toolbar Commands for other types of macro commands.

^!Keyboard Keys

Plays the specified key sequence within NoteTab. Use blank characters as delimiters between the keys to play. To specify plain text, wrap it with the # character. Characters can also be represented as hexadecimal values by using a $ symbol in front of the number. For example, $20 represents the spacebar character and $09 the tab key.

Since version 4.6, the keyboard command supports delay settings between key instruction. The value represents milliseconds and should be preceded with the "&" symbol. Example:

^!Keyboard Alt+V O &1000 Ctrl+Tab &400 Ctrl+Tab

Valid control keys are:

CTRL, SHIFT, ALT (Add UP/DOWN suffix to hold button up or down respectively)

Function keys:

F1, F2, ..., F12

Other keys:

BACKSPACE, TAB, ENTER, ESC, SPACEBAR,

PAGEUP, PAGEDOWN, END, HOME, LEFT, UP, RIGHT, DOWN,

INSERT, DELETE, HELP

Examples:

^!Keyboard CTRL+O #Hello World#

and

^!Keyboard SHIFTDOWN RIGHT RIGHT RIGHT SHIFTUP

and

^!Keyboard ALT+T S M

and

^!Keyboard SHIFT+F2

and

^!Keyboard $4E $6F $74 $65 $54 $61 $62

^!KeyboardDelay nnn (added in v4.6)

Controls the speed of typing with the ^!Keyboard command. nnn specifies the approximate delay in milliseconds between each keystroke. Set nnn to 0 for maximum speed. The scope of this command is limited to the current Clip execution.

^!PlayBack Keys

Similar to the TypeBack command but plays back the specified key sequences (same used by ^!Keyboard command). Works with most programs.


Windows Registry and Shortcuts

Use the following commands and functions to access the Windows registry and create Windows shortcuts.

Commands:

^!ClearRegValue [BaseRoot\]Key[:Name] (added in v4.8)

Deletes the specified name or key in the Windows Registry. If BaseRoot is not defined, then HKEY_CURRENT_USER is used. If a Name is specified, then only that name will be deleted from the Registry. If no Name is specified (no colon), then the key and all Names under it will be deleted. Use with care!

Version 4.83: if the Key value contains a colon, the Clip interpreter will incorrectly assume it marks the limit between the Key and Name elements. To remedy this situation, use a double colon after the key name. Example:

^!ClearRegValue HKEY_CURRENT_USER\Software\c:Beta::UserName=Raymond

BaseRoot can be any of the following values:

HKEY_CLASSES_ROOT

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

^!MakeShortcut ShortcutLocation "Target" ["Arguments"] ["Description"] [CmdShow] ["StartInFolder"] [IconIndex] (added in v4.8, enhanced in 5.7)

^!MakeShortcut ShortcutLocation "Target" ["Arguments"] ["Description"] [CmdShow] ["StartInFolder"] ["IconFile"]

^!MakeShortcut ShortcutLocation "Target" ["Arguments"] ["Description"] [CmdShow] ["StartInFolder"] ["IconFile::IconIndex"]

Creates Windows shortcuts. Syntax:

• ShortcutLocation is the place where the shortcut is created. It accepts the same values as the TypeFolder argument used in the ^$GetSpecialPath(TypeFolder)$ function.
• "Target" is the program to execute, or the document to launch.
• "Arguments" are eventual command-line switches you might want to use with the target program.
• "Description" is an optional parameter you can use to identify the shortcut. If it is left blank, the shortcut name will be the same as the target program name.
• CmdShow defines how the program is opened. It can have one of the following values:

Normal (default if no value specified)

Maximized

Minimized

• "IconFile" sets the file (path and name) containing the icon. If this argument is not specified, the value is set to "Target" if it represents an icon resource.
• IconIndex sets the index of the icon within "IconFile". The first icon has an index value of 0.

Example:

^!MakeShortcut SendTo "^$GetAppFileName$" "" "Open in NoteTab" MAXIMIZED

^!SaveRegValue [BaseRoot\]Key[:Name]=Value (added in v4.8)

Saves the specified value under the key entry in the Windows Registry. If BaseRoot is not defined, then HKEY_CURRENT_USER is used. If no value is specified for Name, the "(Default)" name is used. The maximum amount of text that can be saved this way is 1024 characters. Use with care! Example based on ^$GetRegValue$ example:

^!SaveRegValue HKEY_CURRENT_USER\Software\Beta:UserName=Raymond

^!SaveRegValue Control Panel\International:sDate=/

^!SaveRegValue HKEY_CLASSES_ROOT\.386=vxdfile

Version 4.83: if the Key value contains a colon, the Clip interpreter will incorrectly assume it marks the limit between the Key and Name elements. To remedy this situation, use a double colon after the key name. Example:

^!SaveRegValue HKEY_CURRENT_USER\Software\c:Beta::UserName=Raymond

Functions:

^$ExpandEnv("Str")$ (added in v4.9)

This function expands environment-variable strings and replaces them with their defined values. Example (under Windows XP):

^$ExpandEnv("%systemroot%")$ -> "C:\WINDOWS"

Predefined system variables under Windows 2000 and XP:

ComputerName

ComSpec

HomeDrive

HomePath

HomeShare

LogonServer

Number_Of_Processors

OS

Os2LibPath

Path

PathExt

Processor_Architecture

Processor_Identifier

Processor_Level

Processor_Revision

Prompt

SystemDrive

SystemRoot

UserDomain

UserName

UserProfile

WinDir

In addition, since version 5.7 a variety of system variables can be accessed using ^$ExpandEnv$ with file and folder tokens. For details, view Folder and File Tokens in the Main Help File.

^$GetRegValue("[BaseRoot\]Key[:Name]")$ (added in v4.8)

Returns the value stored under the specified key in the Windows Registry. If BaseRoot is not defined, then HKEY_CURRENT_USER is used. If no value is specified for Name, the "(Default)" name is used. Returns an empty string if the key does not exist. Example:

^$GetRegValue(HKEY_CURRENT_USER\Software\Beta:UserName)$ -> Raymond

^$GetRegValue(Control Panel\International:sDate)$ -> /

^$GetRegValue(HKEY_CLASSES_ROOT\.386)$ -> vxdfile

Version 4.83: if the Key value contains a colon, the Clip interpreter will incorrectly assume it marks the limit between the Key and Name elements. To remedy this situation, use a double colon after the key name. Example:

^$GetRegValue(HKEY_CURRENT_USER\Software\c:Temp::Folder)$

^$GetShellFolder(SystemFolder)$ (added in v4.9)

Returns the path to the specified folder type "SystemFolder". The folder name always ends with a backslash. See below for SystemFolder values and an example for each value of a corresponding path (under Windows 98):

Desktop --> C:\WINDOWS\Desktop\

Templates --> C:\WINDOWS\ShellNew\

AppData --> C:\WINDOWS\Application Data\

Start Menu --> C:\WINDOWS\Start Menu\

Programs --> C:\WINDOWS\Start Menu\Programs\

Startup --> C:\WINDOWS\Start Menu\Programs\StartUp\

Fonts --> C:\WINDOWS\Fonts\

SendTo --> C:\WINDOWS\SendTo\

Recent --> C:\WINDOWS\Recent\

Favorites --> C:\WINDOWS\Favorites\

NetHood --> C:\WINDOWS\NetHood\

Personal --> C:\WINDOWS\My Documents\

Cache --> C:\WINDOWS\Temporary Internet Files\

Cookies --> C:\WINDOWS\Cookies\

History --> C:\WINDOWS\History\

PrintHood --> C:\WINDOWS\PrintHood\

Local AppData --> C:\WINDOWS\Local Settings\Application Data\

My Pictures --> C:\WINDOWS\My Documents\My Pictures\

Administrative Tools -->

C:\WINDOWS\Start Menu\Programs\Administrative Tools\

^$GetSpecialPath(TypeFolder)$ (added in v4.8)

Returns the path name of the specified Windows folder. TypeFolder can have one of the following values:

AppFolder

Desktop

DesktopDir

StartMenu

Programs

Startup

SendTo

Favorites

Recent

CommonDesktopDir

CommonStartMenu

CommonPrograms

CommonStartup

CommonFavorites

^$GetUserRegRoot$ (added in v5.4)

If you are running a non-NT version of Windows (Win95/98/ME), this function returns a value of HKEY_LOCAL_MACHINE, otherwise it returns HKEY_CURRENT_USER. This function can be useful to ensure compatibility with certain registry operations under different versions of Windows. See usage examples under the "NoteTab Shortcuts" section of the Utilities library.


Miscellaneous Commands / Functions

Miscellaneous but useful Clip commands and functions.

Commands:

^!Delay nnn

Adds a delay in 10th seconds before next instruction is executed. nnn is the time value.

^!FileScramble "InputName"[ "OutputName"[ "Key"]] (added in v4.84)

encrypts and decrypts files. Requires the ntb_enc.dll file. This command can automatically detect if the file needs encrypting or decrypting. InputName is the file to encrypt or decrypt. Use the optional OutputName to define the name of the file created by the operation. If the file is going to be encrypted and you don't specify an output name, the name will be based on InputName with the extension ".npw". If the file is going to be decrypted and you don't specify an output name, the original file name will be used. Use the optional "Key" parameter to define an encryption password (max. 255 characters). Make sure you don't forget your password, or you will not be able to restore your encrypted data.

The encryption method is based on the ARC4 (Alleged RC4) algorithm. The Algorithm known as "RC4" is a trademark of RSA Security, Inc. You should not rely on this feature to protect very sensitive data.

^!Goto Label

Continues Clip execution from the specified label defined in the Clip.

^!Help (added in v4.6)

or

^!Help "FileName" (added in v4.6)

or

^!Help "[FileName]" Keyword (added in v4.6)

Displays the indicated Help file or the NoteTab Help file if no parameter is specified. Displays the topic in the keyword table that matches the specified keyword, if there is an exact match. If there is more than one match, displays the Index tab. The following example will display the topics discussing Perl in the NoteTab Help file: ^!Help "" Perl

^!ProgIniLoad [IniName] (added in v4.6)

Loads options from the NoteTab ini file or registry. Optionally, you can specify an alternative INI file (it must exist or else the command sets the error condition). Note that the [AutoLoad] section is ignored by this command.

^!ProgIniSave [IniName] (added in v4.6)

Saves the current program settings into the NoteTab ini file or registry. Optionally, you can specify an alternative INI file (it is automatically created if it does not exist).

^!ReloadLibrary (added in v4.52)

Reloads the current Clipbook library. Useful if another application has modified it.

^!SetErrorLabel LabelName (added in v4.52)

Defines a label to which execution should jump whenever the error flag is set. The scope of this command is limited to the Clip where it was invoked. Note that when an error label is defined, the ^!IfError command is ignored.

^!SetPasteboardDivider DividerText

Use this command to change the Paste Board divider. Accepts tokens to specify new lines (^p) and tabs (^t).

^!SetScreenUpdate [On|Off] (added in v4.52)

Enables or disables updating of the NoteTab application window. Disabling updating when a repetitive sequence of Clip commands affects the text layout can significantly improve the processing speed. The scope of this command is limited to the Clip (and eventual sub-Clips) where it was invoked. When a Clip ends, screen updating is automatically re-enabled. Since version 4.6, the following commands will now force a screen refresh while screen updating is disabled: ^!Prompt, ^!Continue, ^!Skip, ^!Info, ^!StatusShow, and Clip Wizards based on ^?{...} type fields.

^!ShowClipbook [TRUE|FALSE]

Shows or hides the Clipbook window.

^!Sound FileName (or Windows sound)

Plays Wave file or Windows sound (SystemAsterisk, SystemExclamation, SystemHand, SystemQuestion, SystemDefault).

^!UUDecode "InputName"[ "OutputName"] (added in v4.84)

InputName is the file to decode. Use the optional OutputName to define the name of the UUEncoded data file. If you don't specify an output name, the name stored in the encoded file will be used.

^!UUEncode "InputName"[ "OutputName"] (added in v4.84)

InputName is the file to encode. Use the optional OutputName to define the name of the UUEncoded data file. If you don't specify an output name, the name will be based on InputName with the extension ".uue".

Functions:

^$GetAppFileName$ (added in v4.8)

Returns the file and path name of the NoteTab program file. Example, with default folder for NoteTab Pro:

^$GetAppFileName$ -> C:\Program Files\NoteTab Pro\NotePro.exe

^$GetAppTitle$ (added in v4.52)

or

^$GetAppTitle(TitleText)$ (added in v4.52)

Returns the full title of the active application window when no title is specified, or the window matching the specified text.

^$GetCrcFile("Filename")$ (added in v4.84)

Returns the CRC32 (cyclic redundancy check) value of the specified file. Example:

^$GetCrcFile("^$GetAppFileName$")$

^$GetCrcText("Text")$ (added in v4.84)

Returns the CRC32 (cyclic redundancy check) value of the specified text. Example:

^$GetCrcText("^$GetText$")$

^$GetEditorType$

Returns NTS if the editor is NoteTab Std or Light, and NTP if it is NoteTab Pro.

^$GetLibraryName$

Returns the name of the library running the Clip.

^$GetMD5File("Filename")$ (added in v4.84)

Returns the MD5 signature of the specified file. The result is produced in hexadecimal format. MD5 is a hashing algorithm that generates a digital signature, or Message Digest, representing the supplied data. The MD5 algorithm was produced by RSA Data Security, Inc. Example:

^$GetMD5File("^$GetAppFileName$")$

^$GetMD5Text("Text")$ (added in v4.84)

Returns the MD5 signature of the specified text. The result is produced in hexadecimal format. MD5 is a hashing algorithm that generates a digital signature, or Message Digest, representing the supplied data. The MD5 algorithm was produced by RSA Data Security, Inc. Example:

^$GetMD5Text("^$GetText$")$

^$GetPasteboardDivider$

Returns the value of the Paste Board divider.

^$GetProgName$ (added in v4.6)

Returns the full name of the NoteTab variant.

^$GetProgVersion$ (added in v4.6)

Returns the current version number.

^$GetWinPlatform$ (added in v5.4)

Returns the Windows platform type under which NoteTab is running. Possible values are one of the following: Win32_Win, Win32_NT, Unknown. If you're running Win95/98/ME the returned value is Win32_Win, and Win2000/2003/XP/Vista/Longhorn produces Win32_NT. This function is useful to ensure compatibility with operations that need to run differently on each Windows platform.

^$GetWinVersion$ (added in v5.3)

Returns the version of Windows under which NoteTab is running. Possible values are one of the following: Win95, Win98, WinME, NT4, WinXP, Win2000, Win2003, Vista, Longhorn, Unknown.

^$IsAppOnUSB$ (added in v5.7)

Returns True if NoteTab is running with the USB option (see related NoteTab /USB command-line switch).

^$IsOnline$ (added in v5.0)

Returns True if NoteTab detects a connection to the Internet.


Mathematics

The Clip syntax is also capable of calculating mathematical expressions. The advantage of the Clipbook is that you can create Clip Wizards to define the values of variables. You can create Clips that will either paste the result in your document or display it in an information window.

^$Calc(Expression[;Decimals])$

Calculates mathematical expressions. Use the optional Decimals parameter to define how many decimals should be displayed; if this parameter is not used, integers are returned as whole numbers, and real numbers are configured with two decimal figures.

"Expression" can be any mathematical expression using the operators and functions listed under the Calculate in NoteTab topic. You can optionally define how many decimal values should be displayed in the result by placing a figure after the expression separated by a semicolon (;).

For example: ^$Calc(7/11;3)$ will return the result 0.636

You can also add prompts to supply values to variables. The following example will prompt the user to define a value for x and the number of decimals that the answer should display:

^$Calc(Sin(^?[Sin(x): Enter a value for x]);^?[Decimals])$

See the Utilities library for some examples.


Dates

^$GetDate(Date Mask)$

^$GetDate(Date Mask;+/-days)$ (added in v5.7)

Returns current date/time formatted according to the date mask. You can add a second argument to specify how many days are added or subtracted from the current date to form the resulting date.

For example:

This message was written ^$GetDate(mm/dd/yyyy)$

Pasting it in a document will produce the following text (assuming the date is August 31, 1999):

This message was written 08/31/1999

^$GetDateFromInt(DateInteger;DateFilter)$ (added in v5.7)

Converts a date integer value to the format defined by DateFilter. This date integer value represents the number of days that have passed since 12/30/1899. See related ^$GetDateToInt function below. Example:

^$GetDateFromInt(39625;mm/dd/yyyy)$ -> 06/26/2008

^$GetDateToInt[(Date;DateFilter)]$ (added in v5.7)

Converts a date matching the DateFilter format to an integer value. If you do not specify any arguments, then the current date is returned. This value represents the number of days that have passed since 12/30/1899. This format is useful if you want to store the date in a universal way, and which can also be manipulated in calculations. Examples:

^$GetDateToInt$ -> 39625 (assuming the current date is June 26, 2008)

^$GetDateToInt(11/06/2008;dd/mm/yyyy)$ -> 39610

^$GetDay$ (added in v5.7)

Returns the day of the week. 1 for Monday, 2 for Tuesday, etc.

Old syntax prior to NoteTab 4.51:

Note that since NoteTab 4.8, the old format will not work if the expression is built from the values of variables and functions. You should use the ^$GetDate(mm/dd/yyyy)$ function instead.

If you want to use date/time filters in a Clip, use ^[ and ^] to delimit the filter element of the Clip text. For example, if you add the following text to the Clip:

This message was written ^[mm/dd/yyyy^]

Pasting it in a document will produce the following text (assuming the date is August 31, 1999):

This message was written 08/31/1999


Clip Wizard and Fields

Sometimes you may want to complete a Clip text or script before it is actually executed. NoteTab can show Clip Wizards at two different stages during script execution. That is done through the use of square brackets "^?[...]" and curly braces "^?{...}".

When input fields are defined using the square bracket format, the Wizard is displayed before the first Clip instruction is executed/evaluated. The Wizard is built from all such fields encountered in the script. That is how and why you may see multiple input fields in a single Wizard as soon as you click on the Clip while others using curly braces may take a little while to pop up.

After processing the square brackets, NoteTab processes the script a line at a time, (which does not necessarily mean in sequential order). Before a line is executed, the Clip interpreter checks if it contains any Wizard fields with curly braces . If they are present, a Wizard is then built based on the fields contained in the line.

Additionally, Clip functions and variables are processed as NoteTab encounters them in the script. If a function is used in square brackets ^?[Today's date is=^$GetDate$] the actual function would be seen in the prompt because the square brackets are processed first, but the function will not be processed until after it is reached in the script. On the other hand, since curly braces and functions are processed when the line is processed, the date will be shown in the prompt using ^?{Today's date is=^$GetDate$}. The same is true when using variables.

Wizard controls can be simple text fields, masked fields, multiline fields, combobox fields, listbox fields, and checkbox fields. They are defined by parameters placed between the "^?[parameters]" or "^?{parameters}" field delimiters. Parameters can have the following structure:

FieldCaption

(Options)FieldCaption

FieldCaption=DefaultValue

FieldCaption=ListValues

FieldCaption==ListValues

The FieldCaption represents the text used for the field's caption. DefaultValue represents the text displayed in the field, which the user can edit. ListValues represent the text that is used to create the list of values displayed by comboboxes, listboxes, and checkboxes; each value must be separated by a | character. You can optionally precede a list item with an underscore character to make it the default value. Options can define the order in which fields should be displayed, the nature of the control, its height as well as other properties. When multiple options are specified, you must use a semicolon to separate them. The following field options are available:

T=M Type is multiline control without word wrap. Only use with the "^?{...}" field format

T=W Type is multiline control with word wrap. Only use with the "^?{...}" field format

T=C Type is combobox (requires ListValues parameter)

T=L Type is listbox (requires ListValues parameter)

T=A Type is array of checkboxes (requires ListValues parameter)

T=O Type is file open dialog box

T=S Type is file save dialog box

T=D Type is folder dialog box

T=T Type is HTML-tag field, for anchor or image elements

C=L Tag is returned in lowercase format; only used by HTML-tag fields.

C=U Tag is returned in uppercase format; only used by HTML-tag fields.

F=Filter Defines a file dialog filter. Use double quotes around the filter

H=Number Defines a field height measured in lines

S=Number Defines a text-size limit for the field content (measured in characters)

M=Mask Defines a field with an input mask. Use double quotes around the mask

Number Defines field sequence position in Wizard

See also Clip Basics for step-by-step examples explaining Clip Wizards.

Field Examples:

^?[Type a name]

Simple blank text field (one line of text)

^?[(M="(000)_000-0000;0;*")Enter telephone number]

Simple field with input mask

^?{(T=W)Type memo text}

Multiline field with word wrap.

^?{(T=M;H=5)Type memo text}

Multiline field with a height of 5 lines and no word wrap.

^?{(T=M;S=20)Type memo text}

Multiline field which accepts text of up to 20 characters long.

^?[Choose a value=Value1|Value2|Value3|_DefaultValue4|Value5]

Combobox field with 5 items in the list. DefaultValue4 is selected by default because it is preceded by an underscore character. The single equal sign means the user can also enter values that are not contained in the list.

^?[(T=C)Choose a value==Value1|Value2|_DefaultValue3|Value4|Value5]

Combobox field with 5 items in the list. DefaultValue3 is selected by default because it is preceded by an underscore character. The double equal sign means the user can only choose one of the values contained in the list.

^?[Prompt==Value1|Value2|Value3|_DefaultValue4|Value5]

Listbox field with 5 items in the list. DefaultValue4 is selected by default because it is preceded by an underscore character.

^?[(T=A)Prompt=Value1|_DefaultValue2|Value3|_DefaultValue4|Value5]

Checkbox field with 5 items in the list. Items that are checked by default are preceded by an underscore character. The result returned by this type of field contains all the checked items delimited by a semi-colon and double-quotes around each item.

^?[(T=O;F="Delphi Files (*.pas;*.dpr)|*.pas;*.dpr")Open file]

Open File field.

^?[(T=O;S=M;F="Delphi Files (*.pas;*.dpr)|*.pas;*.dpr")Open one or more files]

Open multiple files field.

^?[(T=S;F="Text Files (*.txt)|*.txt")Save as]

Save file field.

^?[(T=T;C=L/U;F="HTML Files|*.*htm*;*.asp;*.css")Prompt]

or

^?[(T=T;F="Image Files|*.gif;*.png;*.jpg;*.jpeg")Prompt]

HTML-tag field

^?[(3)Field1] ^?[(1)Field2] ^?[(2)Field3]

Three fields with position in Wizard defined in parentheses.

Related Commands and Functions:

^!SetWizardLabel "LabelText"

You can change the default main label used in Clip Wizards generated from ^?{} prompts. The scope of this setting is limited to the Clip where it is used. This command must be placed before the ^?{} prompts they should apply to. Assign a blank string to restore the default label text.

^!SetWizardTitle "TitleText"

You can change the default title of Clip Wizards generated from ^?{} prompts, and the title of the messages boxes created by the ^!Info command. The scope of this setting is limited to the Clip where it is used. This command must be placed before the ^?{} prompts they should apply to. Assign a blank string to restore the default title.

^!SetWizardWidth Value (added in v5.7)

Use this command to control the width of the Clip wizard. The argument represents a width percentage value and can be between 20 and 500. This command must precede the first Clip field. The following example creates a Clip wizard with twice the regular width:

^!SetWizardWidth 200

^!IfCancel GoToLabel

Jumps to specified label if a Clip Wizard built from "^?{}" fields has been canceled. If the Clip doesn't contain such a statement or if it does not appear after the call to the Clip Wizard and before the next one, then its execution is aborted.

^$SetDefaultValue(ValueList;DefaultValue)$ (added in v4.6)

This function can be used to set the default value displayed by the Clip Wizard in combobox or listbox fields. It returns the ValueList string with DefaultValue as the default value. If DefaultValue does not exist in the list, it is added to the ValueList text. If DefaultValue is an empty string, then the function returns a list with no default value set. Clip example (each time you activate this Clip, the previous default value is selected):

^!IfFalse ^$IsEmpty(^%ValueList%)$ Skip

^!Set %ValueList%=_1|2|3|4|5|6

^!Set %DefaultValue%=^?{Choose or enter a new default value=^%ValueList%}

^!InsertText Default value = ^%DefaultValue%^p

^!Set %ValueList%=^$SetDefaultValue(^%ValueList%;^%DefaultValue%)$

^$GetDefaultValue(ValueList)$ (added in v4.6)

Returns the default value selected in ValueList. Example: ^$GetDefaultValue(1|2|_3|4|5|6)$ -> 3


Masked Input Fields

 Top Previous

Use the mask to restrict the characters a user can enter into the masked edit control to valid characters and formats. If the user attempts to enter an invalid character, the edit control does not accept the character. Validation is performed on a character-by-character basis.

A mask consists of three fields with semicolons separating the fields. The first part of the mask is the mask itself. The second part is the character that determines whether the literal characters of a mask are saved as part of the data. The third part of the mask is the character used to represent unentered characters in the mask.

These are the special characters used in the first field of the mask:

Character Meaning in mask
! If a ! character appears in the mask, optional characters are represented in the input control as leading blanks. If a ! character is not present, optional characters are represented in the input control as trailing blanks.
> If a > character appears in the mask, all characters that follow are in uppercase until the end of the mask or until a < character is encountered.
< If a < character appears in the mask, all characters that follow are in lowercase until the end of the mask or until a > character is encountered.
<> If these two characters appear together in a mask, no case checking is done and the data is formatted with the case the user uses to enter the data. The character that follows a character is a literal character. Use this character to use any of the mask special characters as a literal in the data.
L The L character requires an alphabetic character only in this position. For the US, this is A-Z, a-z.
l The l character permits only an alphabetic character in this position, but doesn't require it.
A The A character requires an alphanumeric character only in this position. For the US, this is A-Z, a-z, 0-9.
a The a character permits an alphanumeric character in this position, but doesn't require it.
C The C character requires an arbitrary character in this position.
c The c character permits an arbitrary character in this position, but doesn't require it.
0 The 0 character requires a numeric character only in this position.
9 The 9 character permits a numeric character in this position, but doesn't require it.
# The # character permits a numeric character or a plus or minus sign in this position, but doesn't require it.
: The : character is used to separate hours, minutes, and seconds in times. If the character that separates hours, minutes, and seconds is different in the regional settings of the Control Panel utility on your computer system, that character is used instead.
/ The / character is used to separate months, days, and years in dates. If the character that separates months, days, and years is different in the regional settings of the Control Panel utility on your computer system, that character is used instead.
; The ; character is used to separate the three fields of the mask.
_ The _ character automatically inserts spaces into the text. When the user enters characters in the field, the cursor skips the _ character.

Any character that does not appear in the preceding table can appear in the first part of the mask as a literal character. Literal characters must be matched exactly in the edit control. They are inserted automatically, and the cursor skips over them during editing. The special mask characters can also appear as literal characters if preceded by a backslash character (\).

The second field of the mask is a single character that indicates whether literal characters from the mask should be included as part of the text for the edit control. For example, the mask for a telephone number with area code could be the following string:

(000)_000-0000;0;*

The 0 in the second field indicates that the Text property for the edit control would consist of the 10 digits that were entered, rather than the 14 characters that make up the telephone number as it appears in the edit control.

A 0 in the second field indicates that literals should not be included, any other character indicates that they should be included.

The third field of the mask is the character that appears in the edit control for blanks (characters that have not been entered). By default, this is the same as the character that stands for literal spaces. The two characters appear the same in an edit window. However, when a user edits the text in a masked edit control, the cursor selects each blank character in turn, and skips over the space character.

NOTE:

When working with multibyte character sets, such as Japanese shift-JIS, each special mask character represents a single byte. To specify double-byte characters using the L, l, A, a, C, or c specifiers, the mask characters must be doubled as well. For example, LL would represent two single-byte alphabetic characters or a one double-byte character. Only single-byte literal characters are supported.